# CiviForm Docs CiviForm is free, open-source software that helps governments bring benefit and service program applications online, making it easier for residents to find and apply for services, and easier for government staff to build and manage them. Because CiviForm is open source, there are no fees to use the base software. Governments own their deployment and their data, with no dependency on a single vendor. The core CiviForm team at [Exygy](https://www.exygy.com), a certified B Corp, serves as product steward and can provide support with questions, deployment, managed hosting, and custom feature development. If you're new here, start with [What is CiviForm?](https://docs.civiform.us/overview/what-is-civiform). Government staff building and managing forms should head to the [User Manual](https://docs.civiform.us/user-manual/civiform-admin-guide). IT and infrastructure teams should start with the [IT Manual](https://docs.civiform.us/it-manual/sre-playbook). Governments planning to set up programs using CiviForm should start with the [Onboarding Guide](https://docs.civiform.us/user-manual/onboarding-guide). # What is CiviForm? An introduction to the problem and the CiviForm solution. CiviForm is open-source software that helps governments bring benefit program applications online, making it easier for residents to find and apply for services, and easier for government staff to build and manage them. Residents seeking public benefits often face a fragmented experience: Programs may be spread across multiple websites, each managed by a different agency or office, each requiring the same personal information to be entered from scratch. Or programs may not be digitized at all, leaving residents to navigate cumbersome paper forms and phone calls. Government staff face their own version of this problem. Every program office tends to build or buy its own intake solution, or rely on paper forms that return unstructured data that's hard to process and act on. When a form needs to change, staff are often dependent on IT or an outside vendor to make it happen. The result is duplicated effort, inconsistent data, and slow response to changing program needs. CiviForm addresses these problems by giving governments a shared platform to build and publish digital applications in one place. Program staff can create and update forms without writing code or waiting for a deployment. And at the core of the applicant experience is a simple but powerful idea: Residents enter their information once and can reuse it across every CiviForm program they apply to. Because CiviForm is open source, there are no fees to use the base software. Governments own their deployment and their data, with no dependency on a single vendor. When new features are released, every government on the platform benefits. [Exygy](https://www.exygy.com), a certified B Corp, serves as product steward, maintaining the shared codebase and supporting the community of jurisdictions using the platform. *** ## Who uses CiviForm? CiviForm is currently deployed by governments at the city, county, and state level across the United States, including [Seattle](https://civiform.seattle.gov), [Arkansas](https://myarciviform.arkansas.gov), [Charlotte](https://civiform.charlottenc.gov), and [Bloomington](https://civiform.bloomington.in.gov). Use cases range from city benefit and discount programs to statewide workforce and health services to universal housing applications. Across deployments, governments have reduced average application times by 65–96%. The CiviForm product serves four types of users: * **Residents** find and apply for public benefit programs through a single portal in their preferred language. * **CiviForm Admins** are government staff who build, update, and publish application forms using a no-code form builder. * **Program Admins** are government staff who review submitted applications and manage applicant statuses. * **Trusted Intermediaries** are staff at community organizations who apply on behalf of residents they serve, managing their caseload from a dedicated dashboard. ## Is CiviForm right for you? CiviForm is a good fit if your government or team * Offers multiple benefit, assistance, or service programs that require data from residents and currently live on separate sites or use separate forms * Has programs administered across multiple departments or agencies that would benefit from a shared platform * Is still relying on paper or PDF-based applications * Wants program staff to be able to build and update forms without depending on IT or a vendor * Wants applicants to be able to find and apply to multiple programs in one place ## Security and data ownership All applicant data is owned and managed by the deploying government. CiviForm integrates with existing government single sign-on systems via OIDC and SAML, and is built to defend against common security threats including cross-site scripting, SQL injection, and cross-site request forgery. ## Getting started with CiviForm The base CiviForm software is free to use. Governments can deploy and manage their own instance, and the full codebase is available on [GitHub](https://github.com/civiform/civiform). For governments ready to get started: * The [Onboarding Guide](https://docs.civiform.us/user-manual/onboarding-guide) walks through the full process from planning and program assessment through launch and growth. * The [Deployment Guide](https://docs.civiform.us/it-manual/sre-playbook/initial-deployment) covers the technical steps for standing up a CiviForm instance. The core CiviForm team can provide support with questions, deployment, managed hosting, and feature development. [Get in touch](https://civiform.us/contact) to learn more. # How does CiviForm work? Overview of CiviForm users and how the product serves them. CiviForm is a platform for governments to build and manage benefit and service program applications without writing code. The sections below describe what each user type can do, but the underlying model is the same throughout: questions are shared, applicant data carries across programs, and everything is configurable without custom development. When a CiviForm Admin builds an application, they can pull questions from this library rather than creating them from scratch. Because questions are shared, when a resident answers "what is your address?" for one program, that answer is stored and pre-filled the next time that question appears in another application. On the resident side, this creates a single portal where they can find all available programs and apply to multiple without re-entering information. Community organizations can do all of this on behalf of the residents they serve. CiviForm also supports more sophisticated configurations. Forms can be set up to show or hide questions based on previous answers, so applicants only see what is relevant to their situation. Governments can configure eligibility rules so residents can screen themselves before completing a full application. Applications are available in multiple languages, with translations managed directly by program staff. ## CiviForm features for each user type ### Residents Residents use CiviForm to find and apply for public benefit and service programs through a single portal. * Browse all programs available through their government in one centralized location and see which ones they may be eligible for * Use a common intake screener to check likely eligibility before starting a full application * Apply online in plain language, in their preferred language, from any device * Save progress and return to finish an application later * Have information entered for one program automatically pre-filled on future applications * Review and update their information at any time via the Review page [![](/files/kHVFiIkpnMXQJFREkdU7)](https://github.com/civiform/docs/blob/main/docs/.gitbook/assets/landing_page_20251007.png) ### CiviForm Admins CiviForm Admins are government staff responsible for building, publishing, and maintaining program application forms. They can launch and update forms without waiting on IT or outside vendors. * Create, edit, and publish application forms directly in the platform without writing code * Draw from a shared question bank rather than recreating common questions from scratch * Configure forms to show or hide questions dynamically based on previous answers * Set eligibility rules so residents can screen themselves before completing a full application * Manage translations for programs and questions directly in the platform * Update forms at any time; previous versions are preserved for reference [![](/files/AOBnPMfKnY3cizibo1Qi)](https://github.com/civiform/docs/blob/main/docs/.gitbook/assets/program_dashboard_20251007.png) ### Program Admins Program Admins are government staff who review submitted applications and manage program workflows. * Review submitted applications directly in CiviForm with all information organized and readable * Create custom statuses to track applications through the review process * Notify applicants of status changes directly from the platform * Export application data to CSV for use in existing reporting tools or downstream workflows * Access is scoped by program — Program Admins can only view applications and applicant PII for programs they are assigned to [![](/files/s8BF2JFkPDI5l65J5zsT)](https://github.com/civiform/docs/blob/main/docs/.gitbook/assets/review_applications_20251007.png) ### Trusted Intermediaries Trusted Intermediaries are staff at community-based organizations and other third parties who help residents navigate and apply for public benefits. * Create, update, and manage applications on behalf of clients from their own accounts * Manage their full caseload from a single dashboard, filtering by program and tracking application statuses * Access only the data their staff have entered; applicant PII is stored securely and not visible to other organizations * Trusted Intermediary accounts are added and managed by government employees [![](/files/23XuvgmoW6Ktn9uBuHH9)](https://github.com/civiform/docs/blob/main/docs/.gitbook/assets/trusted_intermediary_20251007.png) # Glossary Common terms used across CiviForm. To quickly find a term on this page, use **Ctrl + F** on PC or **Command + F** on Mac. * **Applicant** — A resident using CiviForm to find and apply for government benefit and service programs. The terms "applicant" and "resident" are used interchangeably across the docs. * **Block** — Used interchangeably with *screen*. * **CiviForm Admin** — Government staff who manage CiviForm for their jurisdiction. CiviForm Admins create and manage questions, build program application forms, publish programs, and manage permissions for Program Admins and Trusted Intermediaries. They do not review submitted applications — that is the role of Program Admins. * **Common Intake Form** — A cross-program eligibility screener that helps residents understand which programs they may qualify for before they begin a full application. Also referred to as a pre-screener. * **Enumerator question** — A question type that allows applicants to create a list of one type of entity, such as household members, vehicles, or jobs. * **Enumerator screen** — A screen that contains an enumerator question. Repeated screens can be created from enumerator screens to ask follow-up questions for each entity the applicant has listed. * **Jurisdiction** — A government entity that has deployed CiviForm, such as a city, county, or state. Also referred to as a civic entity. * **Personally identifiable information (PII)** — Any data that could potentially identify a specific person, either directly or by combining it with other available data. * **Pre-screener** — See *Common Intake Form*. * **Program** — A government benefit or service offering that has been configured in CiviForm. Each program has its own application form, eligibility rules, and set of assigned Program Admins. Residents see and apply to programs through the CiviForm portal. * **Program Admin** — Government staff who review submitted applications and manage workflows for a specific program. Program Admins can only view applications and applicant data for the programs they are assigned to. They do not build or manage forms — that is the role of CiviForm Admins. * **Question bank** — A shared library of questions available across all programs in a jurisdiction. When a CiviForm Admin creates a new question, it is saved to the question bank and can be reused in any program application. * **Repeated question** — A question associated with an enumerator question that is asked once for each entity the applicant has listed. For example, a question about employment status asked once per household member. * **Repeated screen** — A program screen created from an enumerator screen that contains repeated questions. * **Resident** — See *Applicant*. * **Screen** — A single step within a program application, displaying one or more questions. Programs are made up of one or more screens, presented one at a time. Also referred to as a block. * **Trusted Intermediary** — A staff member of a community-based organization (CBO) or other third-party organization who applies for programs on behalf of residents they serve. Trusted Intermediaries have their own CiviForm accounts and can manage applications for multiple clients from a dedicated dashboard. * **Trusted Intermediary Group** — A community-based organization or other third-party organization whose staff members are authorized to act as Trusted Intermediaries. Trusted Intermediary Groups and their members are added and managed by CiviForm Admins. * **Version** — CiviForm tracks versions of programs and questions. When a CiviForm Admin publishes changes to a program, a new version is created. Previous versions are preserved for reference and for applications that were already in progress. # CiviForm Admin Guide Welcome to the CiviForm Admin Training Guide! If you are a government employee who creates, publishes, and manages application forms for programs, then you are a CiviForm Admin. With CiviForm, you can manage and create program application forms using a repository of reusable questions. Navigate through this guide to learn the ropes as a CiviForm Admin. {% hint style="info" %} To learn more about features for CiviForm Admin, read [how CiviForm works](/overview/how-does-civiform-work#civiform-admin-experience). {% endhint %} # CiviForm Admin training overview Welcome! Kick off your training by watching the video below about CiviForm, the CiviForm Admin role, and the other users of the tool. {% hint style="info" %} **How do I become a CiviForm Admin?** CiviForm Admins are controlled by a group configured in the admin identity provider. When a person logs in via the admin flow, CiviForm checks if the user belongs to the configured admin group. If so, the user is granted CiviForm Admin privileges. More about admin authentication setup in [Authentication Providers guide](https://github.com/civiform/civiform/wiki/Authentication-Providers). {% endhint %} # How to navigate CiviForm Get oriented and learn how to navigate CiviForm as a CiviForm Admin. {% embed url="" %} Orient yourself to the CiviForm landing page. {% endembed %} At the top of the screen, there is a navigation bar. You can navigate to: * **Programs**: View, create, edit and publish programs. This is the page you see when you log in. * **Questions**: View all the questions you can add to your programs and create new questions. * **Intermediaries**: Create or view Trusted Intermediaries. * **API**: A dropdown containing: * **API keys**: Manage API keys, which enable accessing CiviForm programmatically from other software products. * **Documentation**: View the API documentation. * **Reporting**: The data dashboard where you can view core program metrics. * **Settings** (gear icon): Configure CiviForm settings and feature flags. # Working with programs # Create a program ## Create a program A CiviForm program is a benefits program built by CiviForm Admins. It’s essentially a vehicle to ask questions of program applicants and to collect completed applications. Once you create a program, you’ll need to publish it to make it available. Watch the video to learn how to create a program in CiviForm. You can also follow the step-by-step guide below. ### How to add program information {% embed url="" %} **Tip**: To retrieve a list of all programs, click **Download Exported Data (CSV)** at the bottom of the Programs page. #### Create a program 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Create new program**. 4. Enter information for the program, including the external link for additional program information. 5. Click **Save**.\ The new program appears in the list of programs. **Note**: The internal Program Name field ensures each program is distinct. Once the field is set, it cannot be edited. ## Add or remove questions & screens in a program ### How to add screens and questions CiviForm programs are made up of one or more questions housed in screens. Each program has a default screen. A program can hold multiple screens and each screen should contain a logically themed set of questions (for example, all employment-related questions). Each screen equates to a new page when applying to a program. You can edit both unpublished and published programs. To edit published programs, you need a new version. For more details on versioning, go to [Manage versions for programs & questions](/user-manual/civiform-admin-guide/manage-versions-for-programs-and-questions). {% embed url="" %} #### Add a screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Click **Add screen**.\ The screen appears within the program. 5. (Optional) To modify a screen’s name and description, click **Edit name and description**. # Edit a program Watch the video to learn how to edit programs. You can also follow the step-by-step guide below. ## Learn how to edit admin and applicant information. {% embed url="" %} ### Edit a program You can edit both unpublished and published programs. To edit published programs, you need a new version. For more details on versioning, go to [Manage versions for programs & questions.](/user-manual/civiform-admin-guide/manage-versions-for-programs-and-questions) 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program you created. 3. Click **Edit**. 4. Modify the program information fields. 5. Click **Save**. ## Learn how to edit screens, questions, and visibility conditions. {% embed url="" %} ### Add a question to a screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Add a question to a screen by selecting it from the question bank.\ The question appears within the screen. **Note**: Enumerator or file upload questions must be the only questions on a screen. These question types cannot coexist with others. For example, if you add one of these questions to an empty screen, you can't add any other question types. If you have a screen that already has a question, you can't add an enumerator or file upload question to the screen. ### Remove a question from a screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Find the question within a screen you want to remove and click **Delete**.\ The question is removed from the screen and it returns to the question bank. ### Reorder screens If you have more than one screen in your program, you can organize the screens within the screen tree. 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. To reorder the list, select the screen you want to move and click the up or down arrow. ### Remove a screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Find the screen you want to remove within a program and click **Delete screen**.\ The screen is removed from the program and the questions return to the question bank. **Note**: You cannot delete all screens from a program as a program must have at least one screen. Only once your program has more than one screen can you delete the default screen. # Show or hide questions based on inputs When creating programs, some application questions might not need to be displayed when based on the answers to previous questions. For example, if an Applicant’s date of birth is earlier than the qualifying year, a screen displaying a discount code for older adults is unnecessary. Using a visibility condition, CiviForm Admins can easily show or hide a screen based on the answer to any question within the program. **Important**: If you create a visibility condition based on a question that’s potentially hidden behind a different visibility condition, unexpected behaviors might occur. ### Add a visibility condition 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Edit** for the program you would like to add a condition for. 4. Select a screen you wish to show or hide and click **Edit visibility condition**. 5. On the Visibility Condition page, under **New visibility condition**, select the questions you would like to use for your condition and then click **Add condition**. 6. In the Configure Visibility Conditions page select if the screen should be either **hidden if** or **shown if**. 7. For each question in your condition: 1. Set the **Field** data type. 2. Set the **Operator** value. 3. Enter the **Value**. 4. Click **Submit**. 8. The visibility condition is displayed on both the Visibility Condition page and the screen. For example, “Screen 3 is hidden if *household size question name* Number is less than 2." Multiple allowable values can be specified for a given set of questions in a condition. For example, if a condition uses two questions, household size (number) and household income (currency), multiple combinations of household size and income pairings can be specified that meet the condition. To add additional value groups, click **+Add values** on the Configure Visibility Conditions page and fill in the additional values. ### Edit a visibility condition 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Edit** for the program you would like to add a condition for. 4. Select a screen you wish to show or hide and click **Edit visibility condition**. 5. Click **Edit existing visibility condition**. 6. Follow steps in "Add a visibility condition" for configuring the condition. ### Remove a visibility condition 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Select a screen with a visibility condition and click **Edit visibility condition**. 4. Click **Remove existing visibility condition**. 5. Click **Return to edit screen #**. 6. The visibility condition is removed from both the Visibility Condition page and from the screen. The default statement “This screen is always shown" is displayed on the page. ### Rules for visibility conditions The following rules apply when trying to understand visibility conditions: * There can only be one visibility condition per screen. * You can only add a visibility condition for questions used in previous screens. For example, adding a date question to Screen 2 means it’s available for selection in Screen 3. Questions in Screen 3 are not available for selection. * When using a text field, the value should not be in quotes. * When using the operators "is one of" or "is not one of" on text values, the text should be in a comma-separated list. For example, blue,green,purple. The visibility condition fires if the answer to the question is blue or green or purple. # Manage program eligibility and visibility *Note: Unless otherwise noted, assume that directions apply to both eligibility and visibility logic.* ## Eligibility There are programs that may have strict criteria for eligibility. For example, if an Applicant’s date of birth is earlier than the qualifying year, they are ineligible for the program. Using eligibility conditions, CiviForm Admins can screen applicants who don't meet the minimum requirements for a program early in the application process, as well as show applicants cases when there is a program they may qualify for, based on their previous answers. ## Visibility CiviForm Admins may wish to hide or show certain screens in certain cases to better control program flow. For example, if an Applicant stated they have no dependents in their most recent taxes, they can skip the screen in which applicants provide information on dependents. Using visibility conditions, CiviForm Admins can show or hide certain program screens for applicants, based on their answers to questions on previous screens. ## Adding new conditions When viewing a screen in the program edit view, access to eligibility and visibility conditions are available at the "Add eligibility conditions" / "Add visibility conditions" buttons: ![Program blocks view with Add visibility conditions and Add eligibility condition buttons highlighted](/files/m67mdWOlNTl4GkXYcvFQ) Clicking one of those will bring you to the edit view. You can add a new condition using the "Add Condition" button. ![Edit eligibility condition view with "Add Condition" button highlighted.](/files/DrgNTnVcfGk1HzFP0CIx) ### A note on available questions There may be no available questions to use within conditions. Invalid question types include: * File questions * Enumerator questions. If there are no available questions to use, you may see an alert like the following: ![Alert that states "There are no available questions on this screen with which to set an eligibility condition."](/files/NPjUCKCHY0fpXRoSA7lm) **Visibility conditions** take their questions from all previous program screens, so the alert will show as the following: ![Alert that states "There are no available questions on preceding screens with which to set a visibility condition for this screen."](/files/ymmp56nNRtIAaI5HlQRV) ## Editing conditions On adding a condition, you will be greeted with an empty condition block: ![An eligibility condition with nothing selected and blank/disabled dropdowns.](/files/FmusuwI8zmOaCE9N5BS4) On selecting a question, you will be able to enter values and control the logical conditions. Admins can configure: * **Question:** The question controlling the logic for this subcondition. * **Field:** For question types with multiple pieces of data (e.g. "First Name", "Last Name"), which field is used for this subcondition. * **State:** The logical operator for this subcondition (e.g. "Greater than", "Less than", "Equal to") * **Value:** The value compared to the applicant's answer to this question, for eligibility and visibility decisions. ***Example:** The following applicant will be eligible if they are between the ages of 18 and 35.* ![An eligibility condition with date question selected and values of "age" between 18 and 35.](/files/35CLrbVWijGl7BOvKdi8) ### Adding subconditions You can add multiple *subconditions* within a condition using the "Add subcondition" button: ![An eligibility condition with the "Add subcondition" button highlighted](/files/j2MNmjX7Hv2iWzFyokuu) ***Example:** The following applicant will be eligible if they are between the ages of 18 and 35 **AND** they think a scoop of ice cream should cost $1.* ![An eligibility condition with multiple subconditions. Subcondition 1 is true if the applicant is between the ages of 18 and 35. Subcondition 2 is true if the applicant thinks a scoop of ice cream should cost 1 dollar.](/files/vSyaX9xRSnLNQWELjdkj) ### Multiple conditions Multiple conditions can be composed together for more complex logic. ***Example:** The following applicant will be eligible if (They are between the ages of 18 and 35 **AND** they think a scoop of ice cream should cost $1) **OR** They own a toaster.* ![An eligibility condition with multiple subconditions. Subcondition 1 is true if the applicant is between the ages of 18 and 35. Subcondition 2 is true if the applicant thinks a scoop of ice cream should cost 1 dollar.](/files/hWDK2rXcsBTFZhyrlzSn) ## Saving conditions Clicking the "Save and Exit" button at the bottom of the edit page brings you back to the program view. ![An eligibility condition with the "Save and Exit" button highlighted.](/files/PDETQs3sP7OzQ7JZ8q2c) The program view will now display the conditions that you set: ![The program view, showing "Applicant is eligible if any conditions are true: (1) Sample Currency Question" currency is not equal to $1.00 AND "Sample Date Question" date age is between 18 and 35 (2) Sample checkbox question contains any of toaster"](/files/1s4EPNkuuYXMbbkc9dCL) Clicking the "Edit eligibility conditions" button will return you to the edit view. ![The program view, showing "Applicant is eligible if sample date question date age is older than 18" with the "Edit eligibility condition" button highlighted.](/files/USGLZ38j3duCEJI3ippY) If a screen has *visibility conditions*, the program view will show an icon next to the screen title: ![The program view, showing a screen title with an icon, denoting that the screen has visibility conditions.](/files/V9ZxQuKOLyLqa3fSffyP) ## Troubleshooting ### Unable to add new conditions **Problem:** In the rare case of a CiviForm internal error, you may see the following alert: ![Alert saying "We are experiencing a system error that is preventing further conditions from being added."](/files/BeDVNTx26JxghjEV8bHx) **Possible causes and solutions:** * **Endpoint failures:** This could be due to a transient issue. Save, wait for a few (3-5) minutes and retry. If issues persist, check your endpoint logs for any errors during CiviForm's attempts to add new conditions. # Manage program eligibility (legacy) *Note: Documentation for the revamped version of program eligibility and visibility is available at* [*Manage program eligibility and visibility*](/user-manual/civiform-admin-guide/working-with-programs/manage-predicates) There are programs that may have strict criteria for eligibility. For example, if an Applicant’s date of birth is earlier than the qualifying year, they are ineligible for the program. Using eligibility conditions, CiviForm Admins can screen applicants who don't meet the minimum requirements for a program early in the application process, as well as show applicants cases when there is a program they may qualify for, based on their previous answers. ### Add an eligibility condition 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Edit** for the program you would like to add a condition for. 4. Select a screen you wish to add an eligibility condition for and click **Edit eligibility condition**. 5. On the Eligibility Condition page, under **New eligibility condition**, select the question(s) you would like to use for your condition and then click **Add condition**. 6. For each question in your condition: 1. Set the **Field** data type. 2. Set the **Operator** value. 3. Enter the **Value**. 4. Click **Save condition**. 7. The eligibility condition is displayed on both the Eligibility Condition page and the screen. For example, “Screen 3 is eligible if *household size question name* Number is less than 2." Multiple allowable values can be specified for a given set of questions in a condition. For example, if a condition uses two questions, household size (number) and household income (currency), multiple combinations of household size and income pairings can be specified that meet the condition. To add additional value groups, click **+Add values** on the Configure Eligibility Conditions page and fill in the additional values. ### Edit an eligibility condition 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Edit** for the program you would like to edit a condition for. 4. Select a screen you wish to edit an eligibility condition for and click **Edit eligibility condition**. 5. Click **Edit existing eligibility condition**. 6. Follow steps in "Add an eligibility condition" for configuring the condition. ### Remove an eligibility condition 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Select a screen with an eligibility condition and click **Edit eligibility condition**. 4. Click **Remove existing eligibility condition**. 5. Click **Return to edit screen #**. 6. The eligibility condition is removed from both the Eligibility Condition page and to the screen. ### Rules for eligibility conditions The following rules apply when trying to understand eligibility conditions: * There can only be one eligibility condition per screen (but can be across multiple questions). * When using a text field, the value should not be in quotes. * When using the operators "is one of" or "is not one of" on text values, the text should be in a comma-separated list. For example, blue,green,purple. The eligibility condition fires if the answer to the question is blue or green or purple. ### Allowing applicants to submit ineligible applications By default, eligibility conditions block application submission for ineligible candidates. If you'd like to allow ineligible applicants to submit applications, you can change this in the program settings page. The applicant will not be blocked from submitting an application, but the program admin will still be able to see that the application is ineligible during review. 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. If the program is not already a draft, you must create a draft of it by clicking **Edit**. Return to the **Programs** page after doing so. 4. Click on the dropdown menu corresponding to the draft program. 5. Click **Settings**. 6. Click on the toggle to set eligibility to the desired behavior. # Manage address & service area validation ## How to enable address correction for an address question When an admin adds an address question to a program, they will see a toggle button to enable address correction, with a tooltip that reads: > Enabling address correction will check the resident's address to ensure it is accurate. ![Screenshot 2023-04-04 at 10 47 48 AM](https://user-images.githubusercontent.com/4401157/229875682-42c2b061-80eb-44b0-8c3d-6526023f808f.png) If the address correction feature has not been enabled, the tool tip provides additional information to an admin user: > To use this feature, you will need to have your IT manager configure the GIS service. Once the address correction feature is enabled, an admin user may enable address correction for an address. Only one address question per block can have address correction enabled at a time. ![Screenshot 2023-04-04 at 10 57 08 AM](https://user-images.githubusercontent.com/4401157/229878034-c53253f6-cb5d-4f0c-8825-ef3912b53a5b.png) ## How to enable service area validation To enable service area validation for an address question, an admin user must first enable address correction for an address question. Once that is done, an admin user may add service area validation by following these steps: * Click the "edit eligibility condition" button: ![Screenshot 2023-04-04 at 11 01 52 AM](https://user-images.githubusercontent.com/4401157/229879433-09e196e3-cff4-4138-97d4-555fcc65192c.png) * Find the address question in the list of questions, check the checkbox and click the "add condition" button: ![Screenshot 2023-04-04 at 11 06 31 AM](https://user-images.githubusercontent.com/4401157/229880055-f0db0984-c51f-43f7-99df-8286deafd947.png) * Configure the eligibility condition by adding values and saving the condition: ![Screenshot 2023-04-04 at 11 11 31 AM](https://user-images.githubusercontent.com/4401157/229881051-a2454918-b90d-450f-9b61-ee482c4c52e4.png) # Manage notifications By default, CiviForm sends Program Admins an email every time an application is submitted to a program they manage. To change this: 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Edit** for the program you would like to edit notification settings for. 4. Under **Email Notifications**, select or unselect **Send Program Admins an email notification every time an application is submitted**. 5. Save and publish the program. # How to publish programs Watch the video or follow the step-by-step guide below. {% embed url="" %} Publish your draft program to be live on CiviForm. {% endembed %} ### Publish all draft programs Once a program is created or a new version is launched, the program remains in draft until published. When published, it’s available to both Trusted Intermediaries and Applicants. There can only be one unpublished version in the system at a time and once a version is published, it’s locked and cannot be modified. For more details on versioning, go to [Manage versions for programs & questions.](/user-manual/civiform-admin-guide/manage-versions-for-programs-and-questions) 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Click **Publish all drafts**.\ Any new or versioned program is now available. ### Publish a single draft program Instead of publishing all programs and questions at the same time, you can also publish just a single draft program. 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Locate the draft program you'd like to publish. 4. Click **Publish** on that program's row. If the program has any draft questions, those questions will be published along with the program. However, if the draft questions are also referenced by other programs, the program cannot be published on its own. You can only publish it by publishing all programs as described above under **Publish all draft programs**. # Set a pre-screener You can mark one program as the pre-screener (aka intake form). The pre-screener is pinned to the top of the programs page for applicants in a special **Get Started** section. After the applicant submits the pre-screener, programs they may be eligible for are displayed to them based on their answers. For that reason, you may want to use the pre-screener feature in combination with specifying eligibility conditions on non-pre-screener programs. ![](/files/j3tVvJmMCs4YOAepYjsm) ## Using eligibility conditions in combination with the pre-screener When the applicant fills out the pre-screener, programs they may be eligible for are displayed to them based on their answers. To make the most use out of this feature, set [eligibility conditions](https://docs.civiform.us/user-manual/civiform-admin-guide/manage-eligibility) on the programs using questions that appear on both the pre-screener and the target program. For example, you may create a pre-screener with a question asking applicants for their date of birth. You may have program A that requires applicants to be at least 18 years old and program B that requires candidates to be under 18. Set an eligibility condition for program A specifying that the applicant is eligible if 18 or over. Set the eligibility condition for program B to under 18. Then when the applicant fills out the pre-screener, either program A or B will be recommended to them based on their answer to the date of birth question. ## Creating a program and marking it as the pre-screener 1. Sign in to CiviForm as a CiviForm admin. 2. Click **Programs** on the navigation bar. 3. Click **Create a new program**. 4. Fill out all of the program details and check the **Set program as pre-screener** checkbox. 5. Add questions to the pre-screener as normal. ## Marking an existing program as the pre-screener 1. Sign in to CiviForm as a CiviForm admin. 2. Click **Programs** on the navigation bar. 3. Click **Edit** for the program you would like to set as the pre-screener. 4. Click **Edit program details**. 5. Check the **Set program as pre-screener** checkbox. Note that eligibility conditions cannot be set for the pre-screener, so if you had already created eligibility conditions for this program, they will be removed. ## Viewing which program is the pre-screener 1. Sign in to CiviForm as a CiviForm admin or Program admin. 2. Click **Programs** on the navigation bar. 3. The pre-screener will be labeled. If no program has the pre-screener label, there is no pre-screener currently set. ## Setting a redirect URL for when no eligible programs are found If the applicant fills out the pre-screener and no programs they may be eligible for are found, we display a message to them that contains a link to the civic entity's website where they can find more benefit programs. The message says: ***The pre-screener could not find programs you may qualify for at this time. However, you may apply for programs at any time, by clicking 'Apply to programs'. Or to view additional programs you can visit\*\*\*\* \*\*\*\*`CIVIC_ENTITY_WEBSITE`*** To set the text and URL that are used for `CIVIC_ENTITY_WEBSITE`, you need to set the following [environment variables](https://docs.civiform.us/it-manual/sre-playbook/server-environment-variables) in your deployment script: * `COMMON_INTAKE_MORE_RESOURCES_LINK_TEXT` * `COMMON_INTAKE_MORE_RESOURCES_LINK_HREF` # Set an external program CiviForm admins can add programs hosted outside of CiviForm to reduce the burden on residents of navigating multiple websites to search for relevant programs and information. External programs will be presented to applicants along with other programs, but with a clear indicator that the program opens in a link outside of CiviForm. ## Create an external program 1. Sign in to CiviForm as a CiviForm admin. 2. Click **Programs** on the navigation bar. 3. Click **Create a new program**. 4. Select **External program** as the program type. 5. Add the link to the external program site. Notes: * An external program cannot change its type after creation. * There can be multiple external programs in a CiviForm instance. image ## View external programs 1. Sign in to CiviForm as a CiviForm admin. 2. Click **Programs** on the navigation bar. 3. External programs will be clearly labeled in the program list. Notes: * External programs are not visible to Program admins since external programs have no settings they can manage. image ## How external programs appear to applicants When applicants view available programs, external programs are displayed alongside regular CiviForm programs. When an applicant clicks on an external program card, a modal dialog appears that informs the user that the program will be opened outside of CiviForm. The applicant must accept this modal to proceed, which then opens the external program's website in a new window or tab. {% embed url="" %} # Tag a program with categories CiviForm admins can label a program with one or more categories. These categories serve as filters on the applicant home page, helping residents to find the types of programs they are looking for. Here are some of the available categories: * Education * Childcare * Food * Housing * Transportation ## Steps to add a category to a program 1. Sign in to CiviForm as a CiviForm admin. 2. On the Program List Page, find the program that needs categories. 3. Click the 3-dots menu to the right. 4. Select **Edit**. 5. Click **Edit program details**. 6. Scroll to the section that says "Tag this program with 1 or more categories to make it easier to find". 7. Select one or more of the category checkboxes. 8. Scroll to the bottom of the page and click **Save**. {% embed url="" %} ## How categories will appear to applicants After categories have been added to the programs, the selected categories will show as options to filter programs on the home page. Also, program cards will be labeled with the categories the program belongs to. ![image](https://github.com/user-attachments/assets/6ff21be5-9a38-4e23-8c4e-60fa9f029a5e) ## Additional information * Pre-screener forms cannot be labeled with categories since there is only one pre-screener, making a search filter unnecessary. * Categories have been pre-translated. * At this time, it is not possible to create a custom category, although this will likely be possible in the future. # Working with questions # Manage questions Questions form the structure of a CiviForm program. When a CiviForm Admin creates a question for one of their forms, the question is saved in the global question bank. When programs reuse the same question, all Applicant data related to the question gets autofilled. This reduces duplicate data entry and ensures accuracy by using previously vetted information. ### Create a question Watch the video or follow the step-by-step guide below. {% embed url="" %} Create new questions in the shared question bank. {% endembed %} 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar. 3. Click **Create new question** and select a question type.\ For more details on question types, go to [Question types](#question-types). 4. Enter the information for the question. 5. Click **Create**.\ The new question appears in the list of questions. **Tip**: You might want to develop a naming convention for your questions. For example, address-residence, address-work, etc. ### Edit a question You can edit both unpublished and published questions. To edit published questions, you need a new version. For more details on versioning, go to [Manage versions for programs & questions.](/user-manual/civiform-admin-guide/manage-versions-for-programs-and-questions) 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar and select a question. 3. Click **Edit draft**. 4. Modify the question information fields. 5. Click **Update**. ### Archive a question If a question is no longer in use by any program, you can archive a question. 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar and select a question. 3. Click **Archive**. ### Restore an archived question When you restore an archived question, you can use it in your programs. You can restore an archived question up until the next version is published. For more details on versioning, go to [Manage versions for programs & questions.](/user-manual/civiform-admin-guide/manage-versions-for-programs-and-questions) 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar and select an archived question. 3. Click **Restore archived**. ### Question type requirements All question types have the following configuration options: * Title (text shown to the user) * Description or help text (this is raw text, but if we detect a URL, we can format it as a hyperlink.) * Required or optional Each question may have zero, one, or more validation criteria. * For simplicity, if there are two or more criteria, it's assumed that they're joined with "AND" (all criteria must be met for the answer to be accepted) * The list of supported validation criteria are given under each question type's heading. Each validation criterion may be paired with an error message in case that criterion isn't met. ### Question types You can customize your program to include multiple different question types. The table below shows the supported question types, along with the expected data input. | **Type** | **Use case and expected data** | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Address | An Applicant’s address. For example, residential, work, mailing, school, etc. | | Currency | Currency questions are formatted with a decimal point (.) as a separator between the dollars and cents. Useful for asking income and debt-related questions (e.g. wages, benefits received, loan amounts, etc). | | Checkbox |

Useful when Applicants need to check multiple items to answer the question fully.
Tip: If you want Applicants to select only one option from a group of options, use a Dropdown or Radio Button question instead.
Tip: If a Checkbox question is required, then Applicants must select at least one answer. For checkbox questions where an Applicant could have no answer, consider including a "None of these" option or making the checkbox question optional.

| | Date | Suitable for capturing dates. For example, date of birth, graduation date, employment start date. | | Dropdown | Useful for long lists (>8 items) of static data where a single selection is required. For example, a daycare program restricted to certain daycare sites. | | Email | An Applicant’s email address. | | Enumerator | Allows applicants to create a list of one type of entity. For example, household members, vehicles, jobs, etc. Enumerators do not store question data. Instead, the data is stored within the repeated questions within the enumerator. Enumerators also allow you to dynamically add multiple questions whenever needed, reducing program clutter. For example, you can create a repeater to ask the same questions for every member of an Applicant’s household. Enumerator questions must be the only question in an enumerator screen. For more details, go to [Using enumerator questions & screens in a program.](/user-manual/civiform-admin-guide/working-with-questions/using-enumerator-questions-and-screens-in-a-program) | | File Upload | Allows Applicants to upload files to support their application. For example, PDF files and images (PNG, JPG, GIF). File Upload questions must be the only question in a screen. | | ID | Useful for requesting identification or account numbers. For example, a resident's utility account number. Only digits (0-9) are allowed. The minimum and maximum length for this field can be defined in the question settings. | | Map | Allows Applicants to select a location (point) on an interactive map or a checkbox list that corresponds with the map locations. Useful for helping Applicants understand where on the map the locations they are selecting are located. Admins must be able to provide an HTTP endpoint that returns [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) location data (Point features only) with properties for display name, address, and details URL (field names are configurable). When an applicant selects a location, CiviForm will store the location's feature ID and display name at the time of selection with the applicant's submission. Admins can include a maximum number of selections for this question. For more details, go to [Map questions](/user-manual/civiform-admin-guide/working-with-questions/map-questions). | | Name | A full, legal name. | | Number | Applicants can enter a numeric value. For example, annual household income. Numbers must be integers only with no decimals allowed. Users can increase or decrease the number using the arrow buttons within the field. | | Radio Button | Suitable for a short list (<=7 items) of static items where the Applicant is required to select only one option. For example, simple yes/no questions or employment status. **Tip**: If you want Applicants to select multiple options in a question, use a Checkbox question instead. | | Static Text | A free form field that includes the ability to fully format text using Markdown. See [Using Markdown](/user-manual/civiform-admin-guide/using-markdown) for more information. | | Text | A free form field that can store letters, numbers, characters, or symbols. | | Phone | Accepts two inputs from the user: the country, and the number. The number is a formatted input in the (xxx) xxx-xxxx format. Currently, it supports only US and Canadian numbers. The phone numbers are validated and stored as strings. When the admin views the entered number, they see it in the +1 xxx-xxx-xxxx format. | | Yes/No | Useful for simple binary questions where applicants need to answer yes or no. For more details, go to [Yes/No questions](/user-manual/civiform-admin-guide/working-with-questions/yes-no-questions). | # Map questions Map questions allow applicants to view and select locations on an interactive map. This section covers the detailed setup and configuration options for map questions. ## Setup requirements 1. A publicly accessible HTTP endpoint that provides location data in the GeoJson format 2. Valid [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) data containing Features with: * Unique identifiers (the Feature ID) * Point geometry only (longitude and latitude coordinates) * Properties must include fields for: * Display name of the location * Physical address of the location * URL linking to more information about the location When setting up the GeoJSON, you may use any name for the individual fields. Later, when configuring the map question, CiviForm Admins will be able to specify which GeoJSON property fields contain the required information. #### Sample GeoJSON ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-122.4194, 37.7749] }, "properties": { "facility_name": "Main Community Center", "location": "123 Main St, San Francisco, CA", "more_info_link": "https://example.com/center", "wheelchair_accessible": true, "capacity": "limited" }, "id": "main-community-center" # Feature ID }, { ... }, { ... } ] } ``` ## Configuration options When creating a map question, admins must configure: 1. **GeoJSON Endpoint URL** 2. **GeoJSON Key Mappings**: * **Name key**: Specify which GeoJSON property contains the location's name (e.g., "facility\_name", "location\_title") * **Address key**: Specify which property contains the location's address (e.g., "street\_address", "location") * **View more details URL key**: Specify which property contains the URL for more details (e.g., "more\_info\_link", "website") ![Map question settings](/files/X80NBY2LJ31xbb1TC0ok) Admins can also configure: * **Maximum selections**: Limit how many locations an applicant can choose * **Filters**: [Add filters](#adding-a-filter) based on specific GeoJSON property keys to help applicants find relevant locations * **Tag**: [Configure a tag](#adding-a-tag) that displays on locations with specific property values For example, if you were using the [sample GeoJSON feature](#sample-geojson) You would: 1. Select `facility_name` as the name key field 2. Select `location` as the address key field 3. Select `more_info_link` as the view more details URL field 4. Optionally [add a filter](#adding-a-filter) for `wheelchair_accessible` 5. Optionally [add a tag](#adding-a-tag) for locations where `capacity` equals "limited" ## Adding a filter Filters help applicants narrow down location options based on specific criteria. When you add a filter, applicants will see a dropdown or checkbox interface to filter locations by the values in a specific GeoJSON property. Up to six filters can be added to each map question. To add a filter: 1. Click **Add filter** when configuring the map question 2. Select the **Key** that contains the filter values (e.g., "wheelchair\_accessible", "service\_type", "language\_support") 3. Enter a **Display name** for the filter ![Map question filter setting](/files/8zGVlFbDWdkw8b2zzajS) **How filters work for applicants:** * CiviForm automatically detects all possible values for the specified property across all locations in the GeoJSON data * Applicants see these values as filter options in the interface ![Map question filters](/files/tniNrmOmK7zZpCz6pCvV) **Best practices:** * Use property keys with a limited number of distinct values (e.g., boolean values, categories) * Avoid using properties with unique values for each location (e.g., phone numbers, specific addresses) * Ensure the property exists on all or most locations in your GeoJSON data ## Adding a tag A tag displays on locations with a specific property value. Optionally, an alert for that tag displays to applicants when they select a location with that specific property value. This is useful for notifying applicants about special conditions, requirements, or limitations. To add a tag: 1. Click **Add tag** when configuring the map question 2. Select the **Key** for CiviForm to monitor (e.g., "capacity", "status", "requires\_appointment") 3. Enter the **Value** that triggers the tag (e.g., "limited", "closed", "true") 4. Enter a **Display name** that displays as the tag on a location 5. Optionally, write an **alert message** that will be displayed to applicants that select those locations ![Map question tag setting](/files/1kLWtWMSIArPk3vCkSuN) **How tags work for applicants:** * When an applicant selects a location on the map, CiviForm checks if the tag condition is met * If the selected location has a property that matches the configured key-value pair, the alert message is displayed * The tag is informational and does not prevent applicants from selecting the location ![Map question tag](/files/ltAx3MxgjWfpbUFEHPms) ![Map question alert](/files/WLkplwwJhFp5XyirhfF5) **Best practices:** * Keep alert messages clear and concise * Consider what actions you want applicants to take after seeing the alert * Test the alert with your actual GeoJSON data to ensure it triggers correctly ## Data storage and refresh settings CiviForm stores all the data provided by the GeoJSON endpoint (see [sample GeoJSON](#sample-geojson)). When an applicant makes a selection, CiviForm stores: * The unique identifier of the selected location provided as the Feature ID in the GeoJSON data * The value of the configured name field at the time of selection Note: It is the admin's responsibility to maintain a record of which location corresponds to each Feature ID, as CiviForm only returns these two pieces of information. By default, the stored data won't be automatically updated. To enable automatic data refresh: 1. Set `durable_jobs.map_refresh=true` in your application configuration 2. Once enabled, CiviForm will ping the GeoJSON endpoint every 30 minutes to refresh the data. If the endpoint fails at any point, the data will not be updated and CiviForm will continue to use data from a previous successful call until it is able to successfully refresh the data. This automatic refresh is useful for locations with frequently changing properties (e.g., availability, capacity, or service hours). ## Validation options The map question supports: * Required vs optional selection * Maximum number of selections ## Accessibility considerations To ensure map questions are accessible to all users: * Ensure location names are clear * Include several filters so that applicants can narrow down the list of locations ## Troubleshooting ### GeoJSON endpoint failing **Problem**: CiviForm cannot fetch data from the GeoJSON endpoint. **Possible causes and solutions**: * **Invalid GeoJSON format**: Verify your GeoJSON data is valid using a validator like [geojsonlint.com](https://geojsonlint.com) * **Missing Feature IDs**: Ensure every Feature in your GeoJSON has a unique `id` field * **Incorrect geometry type**: Map questions only support Point geometry. LineString, Polygon, and other geometry types will not display * **Endpoint not accessible**: Verify the GeoJSON endpoint URL is publicly accessible and returns a valid response ### Key mapping not working **Problem**: Location names, addresses, or URLs not displaying correctly. **Possible causes and solutions**: * **Incorrect key selection**: Verify you've selected the correct property keys during map question configuration * **Missing properties**: Ensure all Features in your GeoJSON have the name, address, and URL properties * **Null or empty values**: Check that the properties contain actual values, not null or empty strings ### Filters not showing expected options **Problem**: Filter dropdowns are empty or missing expected values. **Possible causes and solutions**: * **Incorrect key selection**: Verify you've selected the correct property keys during map question configuration * **Inconsistent property names**: Ensure the property exists across locations in your GeoJSON data * **Data refresh needed**: If you recently updated your GeoJSON, wait for the next refresh cycle (every 30 minutes if automatic refresh is enabled) ### Tags not appearing on locations **Problem**: Configured tags don't display on locations. **Possible causes and solutions**: * **Value mismatch**: Verify the tag value exactly matches the property value in your GeoJSON (case-sensitive) ### Data not refreshing **Problem**: Updates to GeoJSON data don't appear in CiviForm. **Possible causes and solutions**: * **Automatic refresh disabled**: Verify `durable_jobs.map_refresh=true` is set in your application configuration * **Endpoint failures**: Check your endpoint logs for any errors during CiviForm's refresh attempts ### Selection data missing in exports **Problem**: Application exports don't show expected map question data. **Explanation**: CiviForm only stores the Feature ID and the name field value at the time of selection. To get complete location information, you'll need to: * Maintain a separate mapping of Feature IDs to full location details * Cross-reference the Feature IDs from exports with your GeoJSON data source # Yes/No questions Yes/no questions allow CiviForm admin to easily setup and customize a question that requires a yes/no answer. ## Creating and configuring a Yes/No question To create a Yes/No question, click "Create new question" and then select "Yes/No" from the question type dropdown. Question text, help text, admin id, and note can be added as usual. Under "Question settings" you'll see four pre-set answer options: "Yes", "No", "Not sure", and "Maybe". "Yes" and "No" are required options and cannot be removed. You can unselect "Not sure" and/or "Maybe" to remove them from the answer options the applicant will see. The Admin ID will be used to represent the question option in the API and in program import/export. The Option Text is the text that the applicant will see. ![Yes/No answer options](/files/CDNcr0CZ4517bTKFloQy) ## Translations The pre-set answer options for Yes/No questions come translated out of the box and there is no need to add translations for them. You will still need to translate the question text and help text like with other question types. # Question export settings When a CiviForm Admin creates a question, they must choose an export setting. The export setting controls whether data will be exported in the demography CSV, which is the CiviForm Admin's exported data. The export setting does not affect the Program Admin's exported data. The CiviForm Admin selects one of the following data export options: **Don't include in demographic export** - the answer won't appear in any way in the exported data. **Include in demographic export** - the raw answer as provided by the applicant will appear in the exported data. **Obfuscate and include in demographic export** - the raw answer as provided by the applicant will not appear in the exported data, and instead, an "obfuscated" answer will appear. Obfuscated means that the applicant's answer to the question is cryptographically obscured, exporting text that is unique to the applicant's answer but does not reveal what the original text was. It is impossible to derive the applicant's original input from the resulting exported value. Only other questions with the exact same answer will have the same exported value. For example, in a social security number question, the following inputs would result in the corresponding outputs: Input: 123-45-6789 Example obfuscated output: d158596dd5a6cae6fcb282832885631553ecc8c8b0bf07f84c4aa691953cd0da Input: 123-45-6780 Example obfuscated output: 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b # Universal and Primary Applicant Information questions ### Universal questions Universal questions are questions that are intended to be used by all programs. When a question is marked as universal, it appears at the top in a separate section in the questions tab and in the questions list sidebar when creating a program. Any question may be set as a universal question. When creating or editing a question, select the following toggle to make the question universal. ![](/files/zFDezRZWx4xPUgr0yBeh) It then shows up in the questions tab, as well as the questions list sidebar. ![](/files/zqs0a25EvLJjdWQ2vF5Q) ![](/files/Ws0HmuFE846MosUJ6IXG) On the programs tab, each program notes how many of the universal questions are used in the program. ![](/files/kH0DJIZ1EoZYHt1kp3OI) If a CiviForm Admin attempts to publish a program that does not contain all universal questions, a warning will be shown, but the program may be published anyway. ![](/files/edoHGCzj3KBSKNk6d2mp) ### Primary Applicant Information questions Primary Applicant Information (PAI) questions are a subset of Universal questions that allow the system to take actions based on answers to those questions given by a logged in or guest user. There are currently four types of questions that may be marked as PAI questions: * Name questions * Email questions * Phone number questions * Date questions (should only be used for date of birth questions) > \[!NOTE] A question MUST be marked as a Universal question before it can be marked as a PAI question. Only one instance of a question type may be marked as the PAI question for that question type at a time. When an applicant answers a question marked as a PAI question, specific actions may be taken using their answer. The current available system actions are: * Searching applications by name, email, and phone number * Emailing guest users status updates about their applications * Pre-populating applications with information entered when a Trusted Intermediary (TI) creates a client * Updating TI client information based on answers to application questions For questions that may be marked as PAI questions, you will see an additional section appear when you toggle the "Set as a universal question" toggle. The "Primary application information" section that appears will describe what system actions apply for this question type, and will allow you to set the question as the PAI question for this question type. Before: ![](/files/3BoaYXqjfw9ycjizIesl) After: ![](/files/cK32fm46lWenPnHhPiZl) # Using enumerator questions & screens in a program CiviForm contains the enumerator question type that offers CiviForm Admins a specialized way of structuring their data. Repeated questions can be created for enumerator questions, which allows admins to ask the same question for each repeated entity the applicant lists for the enumerator question. An enumerator screen allows you to create repeated screens with repeated questions in them. In an enumerator screen, the applicant provides a list of repeated entities (for example, household members). Applicants can view each repeated screen for each repeated entity declared in the enumerator screen. For example, if a program needs to gather name and date of birth information for each of an applicant's children. You can create an enumerator screen with an enumerator question to list the applicant's children, and a repeated screen with the repeated questions for the name and date of birth. You can choose to put both the name and date of birth repeated questions in the same repeated screen, or create two repeated screens with one question in each screen. Enumerators do not store question data. Instead, each repeated question of the enumerator stores the data. An Applicant's answers to enumerator questions are only used to help Applicants track their answers within the repeated questions. A screen can only contain an enumerator when it’s the only question on the screen. Repeated screens are created from enumerator screens. An enumerator screen can be a repeated screen of another enumerator. An enumerator screen's repeated screen appears below the enumerator screen and is indented in the tree. Repeated screens display a label showing the screen they were copied from. When adding repeated screens, the enumerator question in the enumerator screen isn’t copied to the repeated screens. ![](/files/kjjdSz4x2N3IsBA07lY7) ### Create an enumerator question 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar. 3. Click **Create new question** and select **Enumerator**. 4. Enter the information for the question. See table below for the enumerator question fields, along with the expected data input: | **Field** | **Expected data** | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Question text |

The text displayed to the Applicant.

For nested enumerators, the “$this” token is required.

| | Question help text |

The help text displayed to the Applicant.

If the question help text field is used, the “$this” token may be used for nested enumerators.

| | Question enumerator | Can be set to “does not repeat” or to another enumerator when using nested enumerators. | | Question settings |

Entity type: The repeated entity type that’s being enumerated. This should be a singular noun, not plural. For example, “Household member”, not “Household members”.

Minimum entity count: The minimum number of answers the applicant must provide.

Maximum entity count: The maximum number of answers the applicant may provide.

| 5. Click **Create**.\ The new question appears in the list of questions. ### Create a repeated question Any question type can be a repeated question, including the enumerator type. 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar. 3. Click **Create new question** and select the question type you want to use. 4. Enter the information for the question. See table below for the repeated question fields, along with the expected data input: | **Field** | **Expected data** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Question text |

Enter the “$this” token to refer to the name of the repeated entity the Applicant will provide. For example, “Monthly income for $this”, or “$this’s monthly income”. The token appears as highlighted in the preview pane.

For nested repeated questions, you can use “$this.parent” to refer to a higher-level repeated entity. For example, if the top-level enumerator is household members and the current enumerator is household member jobs, “Monthly income for $this.parent from $this” would be something like “Monthly income for Theresa from Hooli”.

| | Question help text | (Optional) If the question help text field is used, the “$this” token may be used. | | Question enumerator | Select the enumerator this question should be a repeated question for. | 5. Click **Create**.\ The new repeated question appears in the list of questions. ### Add an enumerator question to an enumerator screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Select an existing screen with no other questions (since a screen can only contain an enumerator when it’s the only question in the screen) or click **Add screen**. 5. Add an enumerator question to the screen by selecting it from the question bank.\ The question appears within the screen and the “Create repeated screen” button is visible. 6. (Optional) To modify a screen’s name and description, click **Edit name and description**. ### Add a repeated question to a repeated screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Locate an enumerator screen. 5. Click **Create repeated screen**.\ The screen appears at the bottom of the repeated screens list for the enumerator screen. 6. Add a repeated question to the screen by selecting it from the question bank.\ The question bank shows only the questions you can add to a screen, so if there are no questions available that means you need to create repeated questions. The question then appears within the screen. 7. (Optional) To modify a screen’s name and description, click **Edit name and description**. *** |

IMPORTANT: You can only remove an enumerator question if there are no repeated screens.
Similarly, you cannot delete an enumerator screen if there are repeated screens.

| | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### Remove an enumerator from a screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Find the enumerator question within a screen you want to remove and select it.\ The question is removed from the screen and it returns to the question bank. The “Create repeated screen” button is also removed. ### Remove a repeated screen 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar and select a program. 3. Click **Edit** > **Manage questions**. 4. Find the repeated screen you want to remove and click **Delete screen**.\ The screen is removed from the program. *** ### Example: Use Enumerator Question to Collect Household Information Suppose you have a section on a program application form where applicants need to provide information about their household members. **List of Household Members** | **Name** | **Birth Date** | **Relationship** | **Employment Status** | | -------- | -------------- | ---------------- | --------------------- | | | | | | | | | | | | | | | | Example valid values:\ Relationship: "Head of Household", "Spouse", "Child", "Parent"\ Employment Status: "Employed", "Unemployed", "Retired", "Student" *** #### Steps to Collect Household Information **Step 1: Create an Enumerator Question** 1. Go to the **Questions** tab and click "Create new question". 2. Select **"Enumerator"** as the question type. 3. Fill in the details: | **Field** | **Value** | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Question text | `List all members of your household` | | Question help text | Add any helpful text for the applicant | | Administrative identifier | `household_members` | | Question enumerator | Set to `does not repeat` since this is the top-level enumerator | | Question settings - Repeated entity type |

Household member

This is the logical description of the repeated entity or the name that will appear when applicants add entities to or remove entities from the enumerator question. For example, setting this field to 'household member' would show: “add household member”, “remove household member”, “name of household member”, etc, on subsequent screens.

| 4. Click **Create**. *** **Step 2: Create Repeated Questions** Now, create the repeated questions for each piece of information you want to collect about each entity (in this case, `household member`). For this example, we'll create repeated questions for: **Name**: 1. Create a new question of type **"Name"**. 2. Fill in the details: * **Question text**: `What is $this's full legal name?`. (The **$this** token refers to the household member listed by the applicant.) * **Administrative identifier**: `household_member_name` * **Question enumerator**: `household_members` (This is the Administrative identifier of the Enumerator Question created in the previous step.) 3. Click **Create**. **Birth Date**: 1. Create a new question of type **"Date"**. 2. Fill in the details: * **Question text**: `What is $this's date of birth?` * **Administrative identifier**: `household_member_birthdate` * **Question enumerator**: `household_members` 3. Click **Create**. Tip: By asking for the date of birth and not age directly, we can calculate the age, and the benefit is that the value of age is only valid at a specific point of time and becomes stale as time goes on, whereas a person's date of birth stays valid. This also makes for a slightly shorter application for the applicants as opposed to asking both questions. **Relationship**: 1. Create a new question of type **"Dropdown"**. 2. Fill in the details: * **Question text**: `What is $this's relationship to the applicant?` * **Administrative identifier**: `household_member_relationship` * **Dropdown options**: "Head of Household", "Spouse", "Child", "Parent" * **Question enumerator**: `household_members` 3. Click **Create**. **Employment Status**: 1. Create a new question of type **"Radio Button"**. 2. Fill in the details: * **Question text**: `What is $this's employment status?` * **Administrative identifier**: `household_member_employment_status` * **Radio button options**: "Employed", "Unemployed", "Retired", "Student" * **Question enumerator**: `household_members` 3. Click **Create**. *** **Step 3: Add Enumerator and Repeated Questions to Screens** 1. Go to the **Programs** tab and select the program you're working on. 2. Click **Edit**. 3. Create a new screen or select an existing screen with no other questions. * A screen can only have an enumerator question if it is the only question on the screen. 4. Add the enumerator question (`List all members of your household`) to this screen from the question bank. 5. Click **Create repeated screen** to create a repeated screen associated with the enumerator screen. * **Screen name**: `Household member details` * **Screen description**: "Please add each household member's name, birth date, relationship, and employment status." 6. Click "Add question" to the repeated questions for name, age, relationship, and employment status to the repeated screen. *** **Step 4: Configure and Publish** 1. Modify screen names and descriptions as needed. 2. Save your changes. 3. Publish your draft program to make it available to applicants. *** Now, when applicants fill out this program: 1. They will first be asked to list all household members. 2. For each member listed, they will be presented with repeated questions to provide: * Name * Date of birth * Relationship * Employment status This allows you to collect comprehensive household information in a structured manner. # Manage translations for programs & questions CiviForm Admins can translate text for both programs and questions using the CiviForm interface. When an Applicant chooses a language, the entered text is displayed in the application. English is the default language for CiviForm. If CiviForm doesn’t include translations for a requested language, the default language is displayed instead. A warning also appears stating the form is not fully translated into the requested language. **Note**: There’s no user interface for the CiviForm Admin to add or remove translation languages from programs or questions. The list of languages CiviForm can support is set up within the code. You can edit both unpublished and published programs. To edit published programs, you need to click **New Version**. For more details on versioning, go to [Manage versions for programs & questions.](/user-manual/civiform-admin-guide/manage-versions-for-programs-and-questions) Watch the video or follow the step-by-step instructions below. {% embed url="" %} Translate program applications into languages beyond English. {% endembed %} ### Add or edit program translations 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. ![image](https://user-images.githubusercontent.com/98119305/156823969-78ccb796-d08e-422c-9753-b508380e0848.png) 3. Find a **draft** (unpublished) program. * To add or edit translations for a published program, [edit the program](https://docs.civiform.us/user-manual/civiform-admin-guide/edit-a-program) and save a version of the program in the draft (unpublished) state. 4. Click the **three dots button** on the right-hand side. ![three\_dots](https://github.com/civiform/docs/assets/23390490/3c749b5b-b24d-4aba-b73d-a7b57d677d40) 5. Click **Manage translations** in the dropdown menu. ![manage\_translations](https://github.com/civiform/docs/assets/23390490/f00db15e-f674-4fbd-8e84-0c0a958f6135) 6. The default Program details and its custom confirmation texts are displayed in the side.\ \ ![image](https://github.com/civiform/docs/assets/101214724/ca8cea92-77f6-4eba-be3f-5b9656bfd10a) 7. To add a translation, select a language tab and enter the translated text for the Program display name, Program description and custom information page.\ \ ![image](https://github.com/civiform/docs/assets/101214724/0b805465-dd42-417a-b944-a2d06dcdb74b) 8. Click **Save**. 9. To go back to program list page, click **Back** button. ### Add or edit question translations 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar and select an unpublished question.\ \ ![image](https://user-images.githubusercontent.com/98119305/156826335-20d69960-3eb5-4de5-8f5c-f372fb1b9afd.png) 3. Click **Manage draft translations**.\ \ ![image](https://user-images.githubusercontent.com/98119305/156822400-08c25717-8fef-4928-b094-14dda35129e6.png) 4. The default question text and help texts are displayed in the side.\ \ ![image](https://github.com/civiform/docs/assets/101214724/1f1ae520-3c0a-41b1-a6e6-293053d3be43) 5. To add a translation, select another language and enter the translated text for the Question text and Question help text.\ \ ![image](https://github.com/civiform/docs/assets/101214724/ae4aacdd-3e55-4b11-9a63-b28389033c77) 6. Click **Save**. To go back to Question list page, click **Back** button. 7. The **Supported languages** column will display the newly added language.\ \ ![image](https://user-images.githubusercontent.com/98119305/156827418-05e4fd5b-219b-4cb9-a0bc-5d438952af97.png) # Manage versions for programs & questions Questions can be shared between programs. If the wording for a question changes, it does so for all programs that use it. However, programs can be set up to show or hide specific questions based on previously answered questions. These dependencies can be different for the same questions across different applications. To account for this use case, CiviForm allows versioning of programs and questions when making changes instead of overwriting the existing version. This means when Applicants begin an application, they remain on that version even if the program or questions are updated. When you publish all drafts, all changes to programs and questions are published together. The versioning and change publishing system bundles the entire set of configuration objects together in a versioned configuration set using a version number. A given version includes its own question set and program definition set including the program application and data export configuration. This means a version can only reference questions in the same versioned configuration set. Read more about the [data versioning model](https://github.com/civiform/civiform/wiki/Data-versioning-model). ### Update program version 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Programs** on the navigation bar. 3. Locate the program you'd like to update. 4. Click on the three dots to open the dropdown menu for that program. 5. Click **Edit** to create a draft version of the program. 6. Modify the program information fields, edit questions, etc.\ **Note**: You can’t edit the internal Program Name field. ### Update question version 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Questions** on the navigation bar and select a question. 3. Click **Edit** to create a draft version of the question. 4. Modify the question information fields. 5. Click **Update**. ### Rules for versioning The following rules apply when trying to understand versioning: * Individual configuration objects (for example, programs) cannot be versioned independently of the complete version set. * There can only be one unpublished version in the system at a time. * Once a version is published, it’s locked and cannot be modified. * New versions are initialized with a complete copy of the current published version. * Applicants are pinned to the version they began their first program application with. They remain on that program version until it’s been submitted. # Working with applications # Add statuses to a program As a CiviForm Admin, you have the ability to set custom statuses (e.g. Approved, Waitlisted) and email content for each program. Once you create and publish statuses for a given program, the Program Admin will be able to set statuses for each application submitted to their program. For statuses with associated email content, a status change will trigger an email to applicants that used a CiviForm account to submit their application. The applicant will also see the status of their submitted application(s) when they log into their CiviForm account. Additionally, you can choose one of the statuses to be a default status. All new applications will automatically be set to this status, and the associated email for that status will be sent to the applicant. ## To Create a Status 1. Sign in to CiviForm as a CiviForm Admin. 2. Click Programs on the navigation bar and select the program for which you would like to add statuses. 3. Click the three dots on the right side of a draft program. 4. Click Manage Statuses. 5. Click Create a New Status. 6. Enter your status name and (optional) any email text you would like the applicant to receive upon the status change. 7. Repeat steps 5-6 for all statuses you would like to create. 8. For any status you wish to set as default, check the "Set as default status" checkbox when creating or editing the status. **Note**: you must Publish All Drafts in order for your statuses to go live. See [How to Publish Programs](/user-manual/civiform-admin-guide/working-with-programs/publish-a-program) for instructions on publishing. **Tip**: Don’t see Manage Statuses as an option when you click the three dot icon? This is because you must add statuses to a Draft program, not an Active program. **To create a Draft version of your program**: 1. Sign in to CiviForm as a CiviForm Admin. 2. Click Programs on the navigation bar and find the program you are interested in. 3. Click Edit on the right side of the program. 4. Click Programs on the navigation bar to return to the programs page, where you will now see a Draft version of your program. ## To edit or delete a status: 1. Sign in to CiviForm as a CiviForm Admin. 2. Click Programs on the navigation bar and select the program for which you would like to modify a status. 3. Click the three dots on the right side of the program. 4. Click Manage Statuses. 5. Click Edit or Delete. # Download exported data Watch the video or follow the step-by-step guide below to download the demography export for all applications for all programs into a CSV file: 1. Navigate to the programs page by clicking **Programs** in the navigation bar. 2. Click the **Download demographic data (CSV)** button. 3. Select a date range for the data you'd like to export. If you select a large date range or leave it blank, the data could be slow to export. 4. Click the **Download demographic data (CSV)** to begin the export. 5. You will see the CSV file downloaded onto your computer. {% embed url="" %} # Role management # Manage Program Admins Watch the video below or follow the step-by-step guide to learn how to manage Program Admins in CiviForm. 1. Navigate to the programs page by clicking **Programs** in the nav bar. 2. Locate the program you'd like to manage Program Admins for in the list of programs. 3. Click on the three dots on righthand side. If the program has both a draft and active version, make sure to click on the three dots that are in line with the draft version. 4. Click **Manage Program Admins**. 5. To add a new Program Admin, type in their email address and click **Add**. Note that the Program Admin must create their own account before you're able to add them in here. Use the email address that they used to create their account when adding them as a Program Admin. 6. You can also remove someone as a Program Admin from this screen by clicking on the **Delete** button. {% embed url="" %} # Manage Trusted Intermediaries CiviForm Admins are responsible for setting up and managing Trusted Intermediaries. A Trusted Intermediary Group is a Community-Based Organization (CBO) that helps people apply for benefit programs. A Trusted Intermediary is a CBO staff member who interacts with Applicants. Watch the video or follow the step-by-step guide below. {% embed url="" %} ### Create a Trusted Intermediary Group 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Intermediaries** on the navigation bar. 3. Enter information for the group (**Note**: The group name should be unique). 4. Click **Create**.\ The new group appears in the list of groups. **Note**: Once the Trusted Intermediary Group field is set, it cannot be edited. ### Add a Trusted Intermediary to a Trusted Intermediary Group 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Intermediaries** on the navigation bar and select a Trusted Intermediary Group. 3. Click **Edit**. 4. Enter the work email address of the staff member you wish to add. 5. Click **Add**.\ The new staff member appears in the list of groups. ### Delete a Trusted Intermediary Group 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Intermediaries** on the navigation bar. 3. Select a Trusted Intermediary Group and click **Delete**.\ The group and its associated members are removed from the list of groups. **Note**: Deleting a group also deletes the group members. However, program applications submitted by the deleted group remain in the system. ### Delete a Trusted Intermediary Group member 1. Sign in to CiviForm as a CiviForm Admin. 2. Click **Intermediaries** on the navigation bar. 3. Select a Trusted Intermediary Group and click **Edit**. 4. Select a Trusted Intermediary and click **Delete**.\ The Trusted Intermediary is removed from the list of members for the group. **Note**: Deleting a Trusted Intermediary doesn’t remove the program applications submitted by the group member. # Manage API keys CiviForm supports integration with external systems via its HTTP JSON API. The API authenticates requests using API keys managed by the CiviForm admin. For more details on how API keys are used and list of APIs supported, refer to [API Integration](https://docs.civiform.us/it-manual/api). ## API key security ### API key expiration When an admin creates an API key they must specify an expiration for it. This is to ensure that API keys are rotated so that in the event a key is compromised it does not grant indefinite API access to the attacker. Requests made using credentials for an expired API key receive an HTTP 401 status code. ### API key allowed subnet When an admin creates an API key they must specify an allowed subnet for it. Requests made from IP addresses outside of the allowed subnet receive an HTTP 401 status code. ### API key permission grants When an admin creates an API key they must specify what CiviForm resources the key provides access to. It is highly recommended that API keys be given narrow scopes of access e.g. access to one program per key, and that keys not be shared between multiple programs or backend processing systems. Requests made using credentials for API keys that don't have access to the requested resource receive an HTTP 401 status code. ### API key retiring Admins may retire API keys using the admin UI. Retiring is a distinct concept from expiration and provides admins with a way to revoke an API key's access. Requests made using credentials for a retired API key receive an HTTP 401 status code. ## Creating a new API key The CiviForm admin creates API keys in the admin UI. To create a new key: 1. Login as a CiviForm admin 2. Click 'API' in the top nav, then 'API keys' in the dropdown 3. Click 'New API key' 4. Follow the on-page instructions for creating a key 5. Click 'Create' 6. Copy the API credentials string and store it somewhere secure API key credentials are presented only once in the CiviForm UI: on the page shown immediately after the key is created. The credentials are not stored in the database or anywhere else in the system. After navigating the browser page away from that page it is impossible to recover an API key's credentials from CiviForm. This is so that a malicious user with temporary access to a CiviForm admin account cannot simply copy the credentials of an existing API key to gain long term access to the system in a way that would be difficult to detect. # Using Markdown Markdown is a simple formatting tool that allows you to create text links and lists as well as apply bold, italics, font sizes, and other formatting edits to text. CiviForm Admin can use Markdown to format text in six key places within CiviForm: * Program descriptions * Custom confirmation screen messages * Static question text * Regular question text (Note: For regular question text, please limit formatting to bold, italics and text links only. Changing font size or making other edits that alter the flow of text can make question text hard to read) * Question help text * Question options (Note: Markdown only works for checkbox and radio type question options, not for dropdown options. Line breaks and lists do not work for question options at this time) Fields where some or all markdown is allowed will be marked with an indicator: ![Markdown indicator](/files/6L7eSPoQMg1PyOkZapt3) The formatting options currently supported by CiviForm are outlined in the table below along with how to use them. If you would like a formatting option that we do not currently support, let us know! ![Markdown table 1](/files/cNmH4ajyf8jraF5w9DGd) ## Notes and Caveats about working with Markdown in CiviForm ### Font Size Header syntax can be used to change font size. We currently support three font sizes - large, regular, and small. Starting a line with `#` or `##` will create an "h2" size header, which is the largest text possible. Using 3 (`###`) or 4 (`####`) hashes will result in regular sized text. Using 5 (`#####`) or 6 hashes (`######`) will result in the smallest text. Accessibility Note: Generally, more hashes indicates less important text. Folks who are visually impaired often rely on the header tag to let them know the relative importance of text on the page since they might not be able to see differences in font size. ### URLs Urls that start with `http://` or `https://` will be automatically detected as links and have the appropriate formatting applied. Urls that do NOT start with `http://` or `https://` will not be detected as links. All links are set to automatically link out to a new page. Urls used within text links must also include `http://` or `https://` to link out correctly. Examples:\ Correct: `[This link will work!](https://www.example.com)`\ Incorrect: `[This link will not work](www.example.com)` ### Email Addresses Email addresses (Eg. `test@example.com`) are automatically detected as links and formatted accordingly. Clicking on an email address will open the local email program (Eg. Outlook) and create a new email to that address. You can also use email addresses in text links by adding `mailto:` and the email address in the parentheses after the text. Example:\ `[Send email](mailto:test@example.com)` # Migrating programs between environments ## Overview Program import is a feature to allow programs and their associated questions to be imported into a CiviForm environment. Imported programs may be migrated from one CiviForm environment to another or imported from another source. ## Handling question collisions If a program you are importing shares questions with an existing program in your import environment, you can decide whether you want to create a new duplicate question, use the existing question, or overwrite the existing definition in your question bank. "Shared questions" are determined by the question admin name. Here are our recommendations for when to choose which option: 1. Reuse the existing question (Default) * Use this option when you want to import a program into an environment that already has existing programs and you want to reuse the questions in the import environment. * Use this option when you want to import many programs with overlapping questions into a fresh environment. * The newly imported program will benefit from CiviForm's shared question model. * If there are existing programs or questions in the import environment, they must be published before importing with this option. 2. Create a duplicate question * Use this when you are confident the imported question should not be the same as the existing question. Questions imported using this option will not affect any questions in the import environment. * You can find questions that were duplicated, since their admin names will have `-_- a` or another letter attached to it. 3. Overwrite the existing question * Use this option when you want to update an existing question in the import environment with the definition of the question from the program you are importing. * Importing a question with this option will update the question that already exists in the import environment, which means updating any programs that contain that question. We do not recommend using this option in a production environment. * If there are existing programs or questions in the import environment, they must be published before importing with this option. ## Exporting a Program 1. Each program on the program dashboard page has a menu item that says “Export program”. ![Export program image](https://github.com/user-attachments/assets/9a415c91-8ceb-4395-ad0a-6e69100e0e1d) 2. Click this to be taken to the program export page for that program. 3. From there you will have the option to download or copy a json representation of the program. 4. Program export works for programs that are in draft or active mode. Either way they will be imported as drafts into the new environment. ## Importing a program 1. Look for the “Import existing program” link on the program dashboard page. ![Import program image](https://github.com/user-attachments/assets/9554f809-cc4a-4743-a545-83727ad126c7) 2. Click this link to be taken to the program import page and follow the instructions there to import a program. ## Program Settings That Are Not Migrated There are a few program and question settings that are not yet being migrated over. You will have to manually set these in your import environment after importing a new program: * Program images * Program statuses (and their associated translations) * Any categories assigned to the program * TI groups associated with the program * Primary Applicant Info settings applied to questions * "pre-screener" setting on a program ## Potential Errors Situations in which you might get an error include: * Attempting to import a program that is larger than 512,000 characters. * We do not currently support importing programs that are larger than 512,000 characters. If you need to import a program that is larger than this limit, contact the engineering team and we can look into raising the size limit. * Attempting to import a program with an admin name that matches the admin name of an existing program. * You can resolve this by editing the program admin name in the json, but please be careful when doing so and only use lowercase letters with dashes between words. Using invalid characters in a program admin name will result in another error. * Exporting a program from an environment that is on a different CiviForm version than the import environment. * Please try to make sure environments are on the same CiviForm version before migrating programs between them. If they are on different versions, you might see an error about an expected field or translation missing. * Attempting to import a program with program visibility set to “Visible to selected trusted intermediaries only” (shows up as “SELECT\_TI” in the program json) * Since we don’t migrate ti groups with the program, you must select a different visibility for the program before migrating. # Program Admin Guide Program Admins are the government employees who handle applications for programs. With CiviForm, they can integrate the tool into or improve existing workflows. In this Guide, you will find how-to: * [How to become a Program Admin](/user-manual/program-admin-guide/how-to-become-a-program-admin) * [Review completed applications](/user-manual/program-admin-guide/review-completed-applications) {% hint style="info" %} To learn more about features for Program Admin, read [how CiviForm works](/overview/how-does-civiform-work#program-admin-experience). {% endhint %} # How to become a Program Admin Program admins have access only to applications of programs they were assigned to. Assignments are controlled by CiviForm admins on a per-program basis. If Alice () needs access to applications of program "Solar program": 1. CiviForm Admins need to go to Programs list and click "Manage Program Admins" on "Solar program". Then add `alice@mycity.gov` as admin. 2. Alice needs to log in to CiviForm using "Admin login" flow. Logging in using applicant flow won't work. # Review completed applications How Program Administrators can use CiviForm. A Program Admin can review completed applications using CiviForm. Program Admins only have access to applications for the programs they are assigned to manage. For more details, go to [CiviForm data management & security](/overview/how-does-civiform-work). **Tip**: To retrieve a list of all applications, click **Download**, then choose **Download CSV** or **Download JSON** from the dialog. ### Review current program applications 1. Sign in to CiviForm as a Program Admin. 2. Click **Applications** for the program you want to review.\ You’re presented with a paginated list of applications. 3. Locate the form you want to analyze and click **View**. ### Review previous program applications 1. Sign in to CiviForm as a Program Admin. 2. Click **Applications** for the program you want to review.\ You’re presented with a paginated list of applications. 3. Under **Applications for other versions**, locate the version number you want to examine. 4. Click **Applications**.\ **Note**: The number following the Applications link indicates the number of applications present under that version. 5. Locate the form you want to analyze and click **View**. ### Change the status of an application As a Program Admin, you have the ability to change the status of a given application in CiviForm. When an application is set to a status with associated email content, applicants receive an email. The applicant will also see the status of their submitted application(s) when they log into their CiviForm account. 1. Sign in to CiviForm as a Program Admin. 2. Click Applications for the program you want to review. You’re presented with a paginated list of applications. 3. Locate the form you want and click View. 4. At the top of the application, select the status you would like from the dropdown menu of options next to Status. **Note**: A CiviForm Admin must create and publish statuses for your program. To create or modify status options for your program, contact your CiviForm Admin. # Trusted Intermediary Guide Trusted intermediaries are third-parties that residents turn to when applying for programs (e.g. community-based organizations). In this Guide, you will learn how-to: * [Apply to a program on behalf of a resident](/user-manual/trusted-intermediary-guide/apply-to-a-program) {% hint style="info" %} To learn more about features for Trusted Intermediaries, read [how CiviForm works](/overview/how-does-civiform-work#trusted-intermediary-experience). {% endhint %} # Apply to a program Trusted Intermediaries can help residents apply to services or they can alert individual Applicants that programs are open to applications. They can also create profiles for their clients when applying. If the Applicant has applied to programs using CiviForm in the past, and they elected to save their information, CiviForm can reuse the Applicant’s stored information for future applications. CiviForm also allows Trusted Intermediaries to manage multiple clients through the application process. Trusted Intermediary Groups can also view the Applicant data their staff have entered. **Note**: Before a Trusted Intermediary can sign in, they must be added to a Trusted Intermediary Group by the CiviForm Admin. For more details, go to [Manage Trusted Intermediaries](/user-manual/civiform-admin-guide/role-management/manage-trusted-intermediaries). ### Add clients 1. Sign in to CiviForm as a Trusted Intermediary. This will take you to your dashboard. 2. Click the button on the right side of the page that says **Add new client**. 3. Fill in the new client form and click **Save**. 4. Now you can either click **Start an application** or **Back to client list**. ### Apply to a program for a client 1. Sign in to CiviForm as a Trusted Intermediary. This will take you to your dashboard. 2. Here you will see a list of all your clients. You can search for your client by name or date of birth. 3. When you find your client, click **View applications** to start an application for them. It should now say "You are applying for *client name*” on the **Programs and services** page. 4. Find the program you want to apply to and click **View and apply**. This will take you to a page with information about the program. 5. Click **Start an application**. 6. Enter information on each page of the application. Click **Continue** to advance through the program. 7. Click **Submit Application** when finished. # Onboarding Guide This section outlines strategies on how to adopt and implement CiviForm to meet your organization's needs. * **Plan**: Map the needs of your organization and programs in detail to understand where CiviForm can help. * [Organization assessment](/user-manual/onboarding-guide/organization-assessment) * [Program assessment](/user-manual/onboarding-guide/program-assessment) * **Implement**: Work with program administrators to create a better experience for applicants and staff. * [Getting started with service design](/user-manual/onboarding-guide/service-design) * [Journey mapping](/user-manual/onboarding-guide/journey-mapping) * [Discovery, eligibility, and intake](/user-manual/onboarding-guide/discovery-eligibility-intake) * [Consolidating questions across programs](/user-manual/onboarding-guide/consolidating-programs) * [Working with existing tools and processes](/user-manual/onboarding-guide/existing-processes) * [Working across jurisdictions](/user-manual/onboarding-guide/working-across-jurisdictions) * [Data reporting and other integrations](/user-manual/onboarding-guide/reporting-and-integrations) * [Security and privacy considerations](/user-manual/onboarding-guide/security-and-privacy) * **Pilot**: Test applications and processes to refine your approach. * Piloting with staff * Piloting with CBOs * Piloting with residents * **Launch**: Put your new applications out into the world. * **Grow**: Leverage CiviForm to continue to expand access to programs. * Onboarding new programs * Resources for community outreach * **Sustain**: Ensure that this work can continue over time. * [Staffing overview](/user-manual/onboarding-guide/civic-entity-staffing-overview) * Impact measurement and reporting # Organization assessment What is your organization's approach to service delivery? Understanding how residents engage with the government as a whole and with different agencies in particular can help inform where CiviForm can fit into your work. Understanding which programs may be administered by other organizations or jurisdictions can also help consolidate access to those programs for your residents. In addition, understanding technical and operational capacity across programs can help ensure that CiviForm integrates well into your existing workflows. ## What challenges does your organization face in administering programs or services? What opportunities do you see? *Any details are fine, the challenges do not need to be technology-related.* ## What key programs are administered by your jurisdiction (city, county, state)? ## What other programs might residents of your jurisdiction still want to access, even if they are administered by another entity (city, county, state, federal)? *For example, if you are a city, residents may still want to find and access county or state programs.* ## What are the most common ways residents access programs in your jurisdiction? ## What is your organization's existing approach to facilitating benefits access across programs? *Is each program discovered and administered on its own, or can residents access many services at once? Do you manage a central website or tool that lists all programs? Do you have a shared data referral or intake process across programs?* ## What role do community organizations or nonprofits play in connecting residents to programs or administering programs? ## What outcomes is your organization aiming to achieve by expanding benefits access? *For example: Is there a specific focus on reducing burdens for residents, expanding access to specific programs, or supporting specific populations?* ## What role does IT play in supporting programs that administer benefits? *For example: Do you manage a central website or tool that lists programs? Does each program manage their own application process and tooling, or does a central IT team help provide support?* ## What is your organization's technical capacity? *For example, do you run applications on cloud or on-premises infrastructure? Do you have staff who are comfortable with systems administration or application development?* # Program assessment Answering these questions will make it easier to understand how CiviForm and other tools should adapt to the needs of applicants and program staff. Answering these questions can help form a *journey map* of applicants and program staff experiences to inform where and how changes might be implemented. ## What department or organization administers this program? ## What challenges do you face in administering or managing this program? *Any details are fine, the challenges do not need to be technology-related.* ## How do residents typically find out about the program? *Include websites, community organizations, or other channels.* ## Where or how do residents typically submit applications to the program? *Include websites, electronic forms, paper forms, community organizations, program offices, or other channels.* ## Do residents typically apply on their own, or do they receive assistance in applying? *For example, from program staff, call centers, community organizations, social workers, or others.* ## How many applications do you process each (day, week, month, year)? ## What information is necessary to apply to the program? *Share a link to the form or application, or share the questions directly here.* ## How long do applications typically take to be completed (from start to submission)? ## Once submitted, how long do applications take to be processed (from submission to approval)? ## What steps are involved in the life cycle of applying to the program, processing an application, and delivering benefits? *Include the end-to-end life cycle from discovery to the delivery of benefits in as much detail as you can manage, including typical timelines, individuals or roles involved, and steps from both the applicant side and the program/administrative side (and any other stakeholders involved).* For example: *** **Discovery and application** (X minutes total): 1. Resident discovers program through local community group 2. Resident fills out application X via website at [www.example.com](http://www.example.com) with help from local staff member (30 minutes) 3. Resident comes into program office to drop off paper form (30 minutes) 4. Paper form is prepared for processing by program staff in X group (once daily) **Processing** (X days total): 1. Program staff is assigned an application to process (once daily) 2. Program staff begins processing application within X days after submission 3. Program staff from group A enters information into computer system Y 4. Program staff cross-references data in systems Y and Z 5. Program staff calls applicant to verify information D (X minutes) 6. Applicant must bring document D into office (X days waiting) 7. Program staff verifies document D against database Y (X minutes) 8. Application is approved. Status is shared with applicant through system Y (X days) **Delivery** (X days total): 1. Approved application is marked for delivery in system A (once per application manually, 10 minutes) 2. Data is exported from system A to system B for fulfillment (once daily for all applications automatically) 3. Benefits are delivered through mail (X days) (feel free to adjust these section categories or use your own) *** **Discovery and application** (X minutes total): 1. ... 2. ... 3. ... **Processing** (X days total): 1. ... 2. ... 3. ... **Delivery** (X days total): 1. ... 2. ... 3. ... ## What applications, systems, websites, tools, or other resources are used to process information or applications for this program? *Include tools used at all steps, including for application intake, record-keeping, benefits processing and delivery, status notification, data aggregation, reporting, or any other tools.* ## Do you cross-check eligibility information or other details with any other programs or data sources? ## Do you report your program data to any organizations or stakeholders? What do you report and how is it reported? # Getting started with service design At the heart of delivering effective government services is the practice of **civic service design**. Service design strategies aim to understand the needs of residents and craft policies, processes, and services that are tailored to meet those needs. This can include how people find or apply to services, how they interact with programs through in-person staff or digital tools, what programs require from residents throughout the application process, and operational practices such as providing applicant support and reporting on program outcomes. CiviForm is designed to make it easy to implement key best practices in civic service design, such as making program information and applications accessible to residents, supporting workflows for community organizations, notifying applicants of their progress, enabling operational insights through data reporting, and integrating with existing administrative systems and processes. As you work to improve service delivery in your community, service design can help guide how you implement CiviForm to support your specific programs. Service design is grounded in understanding the resident experience as it currently is, and identifying improvements to better meet the needs of residents and better fulfill the mission of each program. The remainder of this guide will focus on how CiviForm can best enable such efforts through the lens of civic service design. Here are excellent resources on service design to read and reference as you work: * [NYC Civic Service Design Tools + Tactics](https://www.nyc.gov/assets/servicedesign/): A comprehensive overview of civic service design practices, including understanding resident needs, mapping processes, and ideating on solutions. Each section includes useful templates and resources for different research and engagement practices. * [Preparing for Human-Centered Redesign](https://beeckcenter.georgetown.edu/report/preparing-for-human-centered-redesign/) * Starting Small with Human-Centered Redesign ([PDF](https://beeckcenter.georgetown.edu/wp-content/uploads/2022/11/Small-ScaleHumanCenteredRedesign.pdf)) * Going Big with Human-Centered Redesign ([PDF](https://beeckcenter.georgetown.edu/wp-content/uploads/2022/11/Large-ScaleHumanCenteredRedesign.pdf)) * [18F Human-Centered Design Methods](https://methods.18f.gov/) * [The Good Services Scale](https://good.services/the-good-services-scale) * [Mapping the applicant experience of benefit enrollment](https://github.com/usds/benefits-enrollment-prototype/blob/master/assets/discovery-findings-mapping-enrollment-Nov2016.pdf) * [Civilla Practica](https://civilla.org/practica) * [Foundations](https://civilla.org/practica/foundations) * [Design Principles](https://civilla.org/practica/design-principles) * [Qualitative User Research](https://civilla.org/practica/user-research) * [Applications](https://civilla.org/practica/applications) # Journey mapping One strategy for understanding the needs of applicants and program staff in more detail is *journey mapping*. Journey mapping is a way of documenting and understanding the end-to-end experience of applicants and program staff as they engage with the program. A *journey map* can give a high-level overview of key interactions, challenges, and opportunities for improvement for different stakeholders throughout their experience with the program.
USDA Journey Map

Example journey map from USDA.

## Mapping what exists The first step to improving residents' experience with programs is understanding their current experience in detail. Working with each program to answer the questions in [Program Assessment](/user-manual/onboarding-guide/program-assessment) can help give a clear picture of each program's user journey across different phases, including discovery, eligibility screening, application submission and processing, determination, delivery, and renewal. A detailed journey map will include touchpoints between residents and staff, tools, processes, timelines, and pain points. In addition to working closely with program staff, conducting research with residents is a key part of understanding existing challenges and opportunities for improvement. ## Understanding what's possible Once you have a journey map of what exists, you can better understand what improvements are possible across the resident journey. Whether it involves simplifying application forms, consolidating many applications into one, or just making a paper application accessible digitally, work with your stakeholders to craft a new journey map that represents a better experience for program staff and residents. # Discovery, eligibility, and intake CiviForm can be a helpful tool even in cases where a program does not require applications, or does not want to use CiviForm to accept applications. As you map the needs of various programs, consider whether CiviForm could play a role in **program discovery**, **eligibility screening**, or **intake** across programs. | Strategy | Description | Pros | Cons | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Application** | Accept complete applications through CiviForm, enabling programs to make final determinations and provide benefits. | Allows re-use of information to simplify application process. Applicants only need to submit information in one place. No further steps required by applicant. | Requires up-front agency effort of onboarding and integration with existing program processes and tooling. | | **Discovery** | Allow residents to quickly find relevant programs in one place, without submitting detailed information. | No need to submit detailed information. No need to integrate with program processes. Can surface programs from [across jurisdictions](https://github.com/civiform/docs/blob/main/docs/user-manual/onboarding-guide/working-across-jurisdictions/README.md). | Resident may need to use another site or form to actually submit an application. No re-use of information as none is being submitted. | | **Eligibility screening** | Allow residents to understand potential eligibility for programs based on key criteria. | Resident can understand potential eligibility for a program before applying. Can surface programs from [across jurisdictions](https://github.com/civiform/docs/blob/main/docs/user-manual/onboarding-guide/working-across-jurisdictions/README.md). | Resident may need to use another site or form to actually submit an application. Less re-use of information as eligibility screening information may differ from detailed application requirements. | | **Intake** | Allow residents to submit a small amount of information that is then sent to relevant program staff for follow-up and additional processing. | Doesn't require significant up-front information from resident. Allows programs to conduct outreach to potentially eligible residents. | Requires manual follow-up from program staff. Additional application information must be collected through other channels to actually make determinations and provide benefits. | ## Discovery CiviForm can serve as a directory of programs available to a resident, even if programs don't accept applications through CiviForm directly. Including programs in CiviForm for discovery allows applicants to find programs relevant to their needs in one place rather than having to search across multiple resources or simply never learning that a program exists. This can be especially useful for programs that offer services rather than benefits, which may involve going to a physical location or calling a phone number, and may not require an application at all. While not an ideal experience for the applicant, it is also possible to list programs and their details within CiviForm specifically to direct applicants to submit an application through a website or form outside of CiviForm. This will require them to re-enter all of their information into the new system, which is a poor experience for the applicant. Whenever possible, programs should allow applicants to submit their applications directly through CiviForm and enable them to leverage the information they've already entered for other programs. See ["Working with existing processes"](/user-manual/onboarding-guide/existing-processes) for more information on how CiviForm can be used by programs that have established tools and processes in place. ## Eligibility Screening CiviForm can also give applicants a quick sense of which programs they may or may not be eligible for, even if they can't apply through CiviForm. Programs and their eligibility rules can be included directly in CiviForm, and programs can then link out to an external application tool or other channel for accessing the program or service. It is still helpful for applicants to get a sense of their likely eligibility across programs, even if they need to take additional steps outside of CiviForm to access the program. ## Intake For some programs, CiviForm can serve as a channel for intake, where preliminary information is submitted through CiviForm then exported for program staff to follow up with an applicant through other channels. This can be useful if you already have tools that manage business rules and processes for program outreach and eligibility determination, but would like another entry point for residents to be brought into these programs. While intake can be a great way to reach people regardless of which programs you've brought on to CiviForm, allowing residents to submit full applications directly via CiviForm allows them to avoid having to re-enter information in other systems when necessary. # Consolidating questions across programs CiviForm enables applicants to re-use previously submitted information when completing applications to new programs. It accomplishes this by unifying question definitions across programs. This is not a technical problem -- it is first and foremost an administrative problem. CiviForm makes it easier to implement information re-use across programs once the administrative work of consolidating question definitions is complete. Here are some best practices for consolidating questions and applications across programs. ## Work with key stakeholders across programs This work involves understanding administrative and policy requirements for different programs, so you must work closely with individuals responsible for administering those programs to understand what they need out of their application forms (and why). In particular, seek out people who have the organizational context to understand why questions must exist, as well as the agency to make decisions about whether or not questions can or should be changed. ## Start with a few programs Begin by mapping questions across one or two key programs to understand where there are similarities and differences in the questions they ask (and how they ask those questions). Starting with a few programs makes the task of mapping questions easier to approach, and provides a solid foundation for adding additional programs incrementally once enough questions have been mapped. ## Understand key shared questions Understand key questions such as name, date of birth, address, contact information, income, household size, assets, and other characteristics such as whether or not someone is a student or has a disability. These questions may seem similar across programs, but there may be subtle differences in what they are actually asking for. For example, questions around income may have different definitions (e.g. in what is considered income, or over what time period). For demographic questions such as race, ethnicity, and gender, understand whether these questions are being asked through free-text fields or categorical fields. If they are categorical, identify similarities or differences in which categories are used across programs. ## Understand the purpose and meaning of each question In order to consolidate and simplify questions across programs, it is essential to understand each question's purpose and meaning. If the meaning of questions can be made consistent across programs, then combining and re-using questions is straightforward. However, if questions seem similar but actually serve different purposes or ask for different information, they may need to exist separately in the question bank to meet different programs' requirements. ### Is it necessary? While auditing questions, understand whether or not a question or requirement is actually necessary. It may be the case that some legacy questions are no longer necessary to administer a program and can be removed entirely. In order to judge with certainty, you must work closely with program administrators to understand a question's origin and purpose. ### Why is it necessary? Different questions may be necessary for different reasons. For example, some questions such as income are simply necessary to determine someone's eligibility for a given program. Other questions such as demographic questions may be necessary (or optional) for mandated reporting purposes. Some questions may be "necessary" simply because some underlying software system or process was poorly designed to require them. Other questions such as past enrollment in other programs might be valuable to help with program operations, but may not be truly required for the administration of the program. Understanding which questions are actually necessary and why they are necessary can help indicate which questions can be consolidated or removed, and which must remain. ### What information is actually necessary? While some questions may seem similar, their underlying meaning may differ subtly, or the actual information required may be a subset of what is asked for. For example, rather than asking for individual information about each household member, it may be sufficient to just ask for the total number of household members. In other cases, it may be necessary to know the age of each household member, in which case asking for that detailed information is justified. Similarly, if only each household member's age is necessary, there is no need to ask for each person's date of birth. ## Encode information so that it can be easily re-used Information can be re-used if each piece of information is represented as a single question in CiviForm. As an example, if you'd like to understand characteristics about someone such as whether or not they are a student or have a disability, asking these questions individually makes them reusable in other applications, whereas asking them all in a single question using a checklist of multiple options requires that another program use the same checklist of options to re-use that information. In this sense, questions should be broken down into their simplest form to enable re-use. However, if such formatting affects the usability of a form -- for example, asking a dozen one-off questions rather than having a single checklist with a dozen options -- it may be best to have separate questions that serve each use case, even if it means that information can't be directly re-used. Alternatively, data can be exported and processed outside of CiviForm to re-encode information to a usable form, even if it wasn't asked as such originally (for example, turning a series of yes/no questions into a checklist or vice-versa). ## Promote accepted best-practices when possible For demographic questions such as race and gender, make a decision to standardize on accepted best-practices when possible. For example, some jurisdictions enable individuals to self-report these fields or have their own set of options which may differ from other standards. While there may be federal reporting requirements that mandate specific language in questions, some jurisdictions or programs may have more flexibility in how they ask these questions and can promote best practices within their organization. # Working with existing tools and processes In order for CiviForm to be implemented successfully, it must be easy for your program staff to continue administering their programs without significantly disturbing their existing workflows and processes. Integrating CiviForm with existing tools and processes allows staff to take advantage of CiviForm's benefits without introducing a substantial learning curve. This approach assumes there are three phases of end-to-end service delivery: (1) Accepting applications, (2) reviewing applications, and (3) delivering benefits/services. Existing tools may serve all or none of these purposes, whereas CiviForm can serve to (1) accept applications, and optionally (2) review applications, depending on the needs and existing approach of each program. Here are a few examples of how CiviForm can integrate with existing tools and processes. ## Accepting applications from CiviForm to process with existing tools Certain programs may already have back-office tools that work well for program staff. In such cases, CiviForm can integrate with those tools as a channel to accept applications without significant additional effort necessary on the part of program staff. ### CiviForm as the primary channel for accepting applications | | Accept applications | Review Applications | Deliver benefits/services | | ----------------- | ------------------- | ------------------- | ------------------------- | | **CiviForm** | ✅ | ❌ | ❌ | | **Existing tool** | ❌ | ✅ | ✅ | If a program doesn't have a significant existing online application (e.g. primarily paper, phone, or walk-in applications), but does have existing back-office tools for application review and processing, then CiviForm can serve as the primary resident-facing channel through which the program accepts applications online. When residents submit applications through CiviForm, the data can be exported using the API and ingested into the existing tool for program staff to review and process as they normally do. ### CiviForm as a secondary channel for accepting applications | | Accept applications | Review Applications | Deliver benefits/services | | ----------------- | ------------------- | ------------------- | ------------------------- | | **CiviForm** | ✅ | ❌ | ❌ | | **Existing tool** | ✅ | ✅ | ✅ | If a program already has an online form for accepting applications that the program wishes to keep, CiviForm can be used as a secondary channel for accepting applications. Similar to the option above, application review and processing takes place in existing tools -- CiviForm just acts as another source of applications. ### Keeping tools in sync In the examples above, program staff do not need to interact with CiviForm at all, since it is simply being used as another channel for accepting applications into existing back-office tools. However, depending on the remainder of the process, it may be important to keep specific information in sync across existing tools and CiviForm. For example, if you wish to communicate program status updates via email to applicants using CiviForm, that information must be updated in CiviForm, either via the interface or through the API. However, if status updates are communicated through existing tools, then no such integration back into CiviForm is necessary and CiviForm's status update feature can be disabled for that program. Similarly, if additional information needs to be collected from an applicant, if that information is collected through a tool other than CiviForm, it will not be apparent to the applicant that their information has been updated. In this case, asking the applicant to submit the additional information from within CiviForm directly, or having a mechanism to feed the new information back into CiviForm via the interface or API may be necessary to ensure a good applicant experience with consistent information across tools. Additionally, if information requirements change in existing forms or online applications, mechanisms must be put in place to update CiviForm's forms to match those changes and ensure consistency across different channels. #### Linking data with existing accounts ### CiviForm for discovery or eligibility screening Even if CiviForm is not used to accept applications for a given program, it may be valuable as a tool for discovery or eligibility screening that then directs applicants to an existing application form. See "[Discovery, Eligibility Screening, and Intake](/user-manual/onboarding-guide/discovery-eligibility-intake)" for more information. ## Accepting and reviewing applications within CiviForm If a program doesn't already have a back-office application review tool or is looking to replace an existing tool, program staff can directly use CiviForm to review applications. For simple programs, this enables staff to take advantage of CiviForm's built-in features such as status tracking, status notifications, and note-keeping. For more complex programs, additional steps may be required for the delivery of benefits/services after applications are approved within CiviForm (for example, exporting data to a payment processor or another system to disburse funds, or referring someone to a service provider for next steps). ### CiviForm as the primary tool for reviewing applications | | Accept applications | Review Applications | Deliver benefits/services | | ----------------- | ------------------- | ------------------- | ------------------------- | | **CiviForm** | ✅ | ✅ | ❌ | | **Existing tool** | 🟡 | ❌ | 🟡 | If a program wishes to use CiviForm as the primary interface through which applications are reviewed, CiviForm can perform this functionality out of the box. Program administrators can review applications, keep internal notes, update an application's status, and send notifications to applicants when their application status changes. This approach can be taken regardless of whether or not there are existing channels for application intake; however, administration may be simpler if a program chooses to standardize on using CiviForm for application intake (for example, encouraging individuals to apply through CiviForm, or having program or CBO staff submit walk-in or phone applications through CiviForm on behalf of residents). Otherwise, there will be separate review processes for different application channels. ### CiviForm as a secondary tool for reviewing applications | | Accept applications | Review Applications | Deliver benefits/services | | ----------------- | ------------------- | ------------------- | ------------------------- | | **CiviForm** | ✅ | ✅ | ❌ | | **Existing tool** | 🟡 | 🟡 | 🟡 | If there is already a tool used for reviewing applications that a program wishes to keep, CiviForm can be used alongside that tool, albeit at the cost of having two different review processes. This may be useful in a state of transition as a program consolidates to use one tool (whether CiviForm or the existing tool), or if there is a way to consolidate the remainder of the delivery process after applications are reviewed across tools. Understanding the primary channels for accepting applications and the downstream processes after applications are reviewed can help make a decision about how to best integrate CiviForm within a program's workflow. ## Other considerations Consider these other factors when integrating CiviForm with existing tools. * Can the program's existing tool ingest data from external sources via an API? * What is your IT team's preferred approach to running data import/export pipelines? * What is an acceptable frequency for applications to be exported from CiviForm and imported into other systems? * What processes must be implemented to ensure breaking changes to forms or APIs are accounted for across systems? * What are security or privacy requirements for these integrations? See "[Working across jurisdictions](/user-manual/onboarding-guide/working-across-jurisdictions)" and "[Security and privacy considerations](/user-manual/onboarding-guide/security-and-privacy)" for more details. # Working across jurisdictions While your program may be administered by and for your jurisdiction, there are likely other programs administered by federal, state, or local agencies that are also relevant to the residents of your jurisdiction. They may not know or care that certain programs are administered by the city, county, state -- they just need help. Surfacing programs from other jurisdictions can be a powerful way to connect residents with the services they need, regardless of where those programs are administered. ## Integrating with other application systems It's likely that programs operated by other jurisdictions already have existing tools and processes for accepting applications and delivering services. In this case, one possible approach is to work directly with those programs to establish data integrations with their existing systems as described in "[Working with existing tools and processes](/user-manual/onboarding-guide/existing-processes)". If direct integrations are seen as too challenging, other approaches may include: * Exporting applications from CiviForm as PDFs and emailing them to programs if they accept email submissions. * Submitting applications directly through existing program websites via a headless browser. This can only be done if the existing website allows submissions without creating an account, and it may still require permission from the program. These approaches are likely to provide a worse experience than direct integrations, so they should only be pursued if more direct approaches fail. ## Incremental steps: Discovery, eligibility screening, and intake If it seems infeasible to support submitting applications to programs in other jurisdictions, consider surfacing programs in other ways. As described in "[Discovery, Eligibility Screening, and Intake](/user-manual/onboarding-guide/discovery-eligibility-intake)", it may still be valuable to surface programs from other jurisdictions to help someone discover them if they are relevant to their needs. Additionally, providing screening functionality for that program can still help someone know whether or not it may be worth applying to with minimal marginal effort as they are screened for other programs within CiviForm. Finally, leveraging CiviForm for intake or referral to programs in other jurisdictions can directly connect someone to the right person for continued support. ## Security and privacy considerations It is essential that applicants understand how their information is being used when submitting an application from within CiviForm. If you plan to share information beyond your jurisdiction, [clearly and plainly communicate](https://www.plainlanguage.gov/guidelines/) where that information will be sent and how it will be used so that applicants can make informed decisions about whether or not they'd like to apply. See the "[Security and privacy considerations](/user-manual/onboarding-guide/security-and-privacy)" section for more information. ### Data sharing agreements Sharing information across jurisdictions may require a data sharing agreement. For more information, see the guide "[Data Sharing to Build Effective and Efficient Benefits Systems](https://bdtrust.org/bolstering-benefits-access-introducing-benefits-data-trust%E2%80%99s-new-data-sharing-playbook/)" ([PDF](https://bdtrust.org/data-sharing-to-build-effective-and-efficient-benefits-systems_january-2023.pdf)) by Benefits Data Trust. # Data reporting and other integrations CiviForm provides administrators with metadata about programs and applications, enabling actionable insights that can improve residents' experience in accessing programs. ## Leveraging data to improve program operations Because CiviForm includes metadata from across programs, administrators can have visibility into applicants' experience across programs in CiviForm. This includes key metrics such as how long it takes to complete an application, which questions applicants might be struggling with, and which programs people tend to cross-apply to. Such metrics can inform changes that lead to direct improvements in a specific program's application experience. Additionally, administrators can analyze metadata to assess which communities are or aren't being reached by a given program, which can in turn inform targeted outreach or other local efforts to expand access. {% hint style="info" %} If you are interested in measuring additional aspects of your programs, consider some of the metrics outlined in Code for America's [National Safety Net Scorecard](https://codeforamerica.org/programs/social-safety-net/scorecard/the-national-safety-net-scorecard/). {% endhint %} ## Sources for reporting Here are key sources for accessing reporting information in CiviForm. ### CiviForm reporting dashboard CiviForm has a built-in dashboard that administrators can use to see core program metrics such as the number of applications and the distribution of application completion time. More metrics are being added over time to provide administrators with insights into their programs out-of-the-box. ### Application analytics CiviForm supports integration with common web analytics tools. Such tools can provide page-level analytics on how applicants are progressing through applications, which can indicate which questions may need to be removed, adjusted, or improved to simplify the application process. The easiest way to get this tracking set up is via Google Analytics. For instructions on how to set up Google Analytics on your site, go to the [Google Analytics Help Center](https://support.google.com/analytics/answer/9304153?hl=en). ## Exports for external reporting Information in CiviForm can be exported to integrate with existing reporting tools, analyses, or workflows. This is helpful for combining information from CiviForm with other sources to give an even broader view of the applicant experience. It can also help make insights about programs available to broader stakeholders (for example, program administrators, policymakers, or the public) through publications or other reporting channels. ### Combining information with other sources Some analyses may require combining information from CiviForm with data from other sources. For example, CiviForm has information on how long it takes for someone to complete an application, but in order to know how long start-to-finish service delivery takes, data must be incorporated from downstream systems that manage later steps in the process of delivering services. Similarly, a complete assessment of responsiveness and access for a given program requires integrating metrics from non-CiviForm channels, such as phone calls or office visits. ## Collecting feedback from residents In addition to these passively measured proxies for residents' experiences with specific programs, CiviForm can also serve as a channel for the direct and active collection of feedback from programs. For example, a feedback or satisfaction survey can optionally be added to the end of program applications when they are configured in CiviForm, or throughout the site via third-party tools. # Security and privacy considerations Residents seeking public assistance are often required to submit personal information to government programs without a clear sense of why that information is being submitted or how it is being used. Such a vulnerable interaction can be especially burdensome on someone in a time of need. As temporary stewards of residents' information, government programs have a responsibility to establish and maintain trust in how they manage residents' information and experiences. Here are some considerations to take into account when managing application information in CiviForm. ## Informing residents Programs should [clearly explain](https://www.plainlanguage.gov/guidelines/) to residents how their information is being used when submitted through CiviForm, both across programs and for individual programs. For example, communicating the full application process for a given program in its description can help residents understand what happens after they submit their application, including follow-ups or any other information that may need to be provided. Additionally, explaining why certain pieces of information are required and who will be reviewing them can help give residents confidence and trust in the application process. ## How information is managed in CiviForm When an applicant submits information via CiviForm, that information is submitted to a specific program. Administrators of that program can view any application submitted to that program, but they cannot view information the applicant has submitted to other programs. That is, from each program's perspective, the only information a program administrator can see is the information that the applicant has explicitly submitted to that program. Once an application is submitted, the applicant's submitted information is stored in a database to be re-used when the applicant chooses to apply to another program, but it is not otherwise accessible outside of an application that has been submitted to a specific program. When an applicant begins an application to another program, their previously-submitted information in CiviForm is used to pre-populate the new form with any questions they may have answered from other programs. Their information is not visible to the new program until the new application to that program is submitted, at which point only the information in that new program's application is visible to the new program administrators. ### Who can export information Information in CiviForm can be exported by CiviForm Administrators, either via the [demography export UI](https://docs.civiform.us/user-manual/civiform-admin-guide/question-export-settings) or through [CiviForm's API](https://docs.civiform.us/it-manual/api). When API access is configured, each API key must be explicitly assigned a list programs that it has permission to access (i.e. an API key can be configured to allow access to only one program, or to multiple programs). CiviForm Administrators do not have inherent ability to view application information, but CiviForm can be configured to grant CiviForm Administrators that permission. Program administrators can only view and export information for programs to which they are assigned. Importantly, program administrators can view and export *any application that has been submitted to their program*. ## Managing information across programs If certain application information will be deliberately shared across programs by the organization administering CiviForm (for example, through a common intake form that is then sent to other programs as a referral), it is essential to communicate this process to residents and ask for their approval on which programs their information should or shouldn't be shared with. Providing a clear explanation for how common intake information might be used (e.g. for proactive outreach from programs) can help residents understand whether or not they see value in having their information shared with other programs. ## Working with trusted intermediaries Trusted intermediaries can submit and modify applications on behalf of residents. When a trusted intermediary submits an application, any other staff member assigned to that trusted intermediary group can also view and modify each application submitted through that trusted intermediary. # Staffing overview This document describes long-term CiviForm staffing needs for a deploying civic entity. Those needs include a non-technical administrative role, and technical roles to support the functioning of the software system. ### CiviForm administrator The CiviForm Admin user role has the ability to define questions, designate data anonymization settings, define program applications, perform anonymized bulk applicant data exports, designate program administrators, and designate trusted intermediaries. For programs to reuse applicant data, they must have harmonized data requirements, which requires someone to coordinate those data needs across programs. This is a natural fit for the CiviForm admin. The role requires someone who is comfortable working with computers but it is not a technical role – all tasks can be completed using the CiviForm UI. Most importantly, the role requires someone who is able to interface with a large number of program staff to understand their data needs and design user-friendly application questionnaires with the CiviForm tool. ### Technical staff Broadly speaking there are two options for technical staffing. One option, "keep the lights on", describes a minimum level of skill and staffing to keep a CiviForm deployment usable at a basic level. The other option, "custom code and incident response self-sufficiency", describes a minimum level of skill to take advantage of the opportunities for data integration that CiviForm presents. #### Keep the lights on **Two part-time IT professionals minimum** *Note: this estimate is for a CiviForm deployment to a major public cloud provider. On-prem deployments require additional resources and an assessment of the civic entity's IT capabilities for an accurate estimate of an on-prem CiviForm deployment's IT staffing needs.* We recommend at least two part-time technical staff for supporting CiviForm at a minimum viable level of service. Two is the minimum level of redundancy necessary to ensure incident response availability. The equivalent of one FTE is the anticipated minimum for maintenance and operations efforts. At this level of staffing we expect the CiviForm deployment to stay up to date with the latest security and feature patches from the mainline project. At this level of IT staffing incident response involves contacting the mainline open source team and waiting for their availability for resolution. Skills needed: * familiarity with web services and basic web application architecture * familiarity with command line interfaces * basic familiarity with web security (e.g. provisioning SSL certificates) * some knowledge of computer networking – IP addresses, DNS, ports, etc * experience maintaining web servers in a cloud environment #### Custom code and incident response self-sufficiency **Two full time software developers minimum** Staffing two full time software developers or more would allow for code-level customizations and a readier incident response posture. At this level of staffing, the civic entity is able to investigate and resolve production incidents independently without relying on the mainline open source developers. The majority of those developers' time however could be spent on feature work which could include generic features and enhancements to the core system desired by the civic entity and/or custom features such as integration with external systems for administering programs (e.g. populating entries in a vehicle licensing database with applications submitted through CiviForm). Additional skills needed: * proficiency in Java or another statically typed language (e.g. C#, Go, or TypeScript) * familiarity with relational databases * understanding of web application security best practices * comfortable working in open-source software ecosystems # Technical Deployment Guide # Initial Deployment This guide is for Systems Administrators, IT managers, SREs, or DevOps folks. It explains how to do an initial deployment of CiviForm into your production cloud environment. CiviForm has the following deployment options: * Can be deployed into AWS using [Terraform](/it-manual/sre-playbook/initial-deployment/terraform-deploy-system). * Can be custom deployed in cloud or on-prem using [CiviForm docker image](https://hub.docker.com/r/civiform/civiform) directly. This is not recommended, as it requires more configuration and maintenance. Additionally using the CiviForm Terraform-based deployment system is tested thoroughly and you will have less chance of unexpected breakage using it. ## Overview This section describes the tasks necessary to deploy CiviForm to new infrastructure. Many tasks can and should be done in parallel. Tasks may vary depending on the specifics of each organization's needs, but the high-level components remain relevant. ### Information you will need The following details are necessary for the initial deployment. A staging environment can be brought up without most of these values, but you will need all of them for a complete production deployment. Deciding on some of them might require coordination across different departments, so it is helpful to start tackling them early. * The infrastructure you wish to deploy on (e.g. a specific cloud provider or on-premises infrastructure). * If using a cloud provider, the region you wish to deploy in. * An authentication provider for administrators (including `client_id`, `client_secret`, and `discovery_uri` details). * An authentication provider for applicants (including `client_id`, `client_secret`, and `discovery_uri` details). * Two domain names for your deployment (one for a staging environment, and one for the production environment). * Government logo images for branding * A support email address to display on the site * An understanding of which of your [existing systems you would like to integrate with](/user-manual/onboarding-guide/existing-processes) via CiviForm's API. * SSL certificates for domain names and/or load balancers. # Terraform deploy system Terraform is an infrastructure-as-code tool that allows you to define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. CiviForm provides Terraform configuration files that allow you to deploy CiviForm on AWS. Knowledge of Terraform is not required to run them, but reading the high-level [Terraform overview](https://www.terraform.io/intro) may be useful. More detailed information on our deploy system can be found in our [developer docs](https://github.com/civiform/civiform/wiki/Deploy-System). ## Setup ### Outside configuration You will need some values that are configured outside of CiviForm before you start the setup. Some of the steps are optional, meaning that you can bring up a staging environment and get the app working without them, but they will need to be completed for a production setup. * (Optional) Admin auth client\_id, client\_secret, and discovery\_uri. See [Authentication Providers](https://github.com/civiform/civiform/wiki/Authentication-Providers) for more details on your type of provider. * (Optional) Applicant auth client\_id, client\_secret, and discovery\_uri. See [Authentication Providers](https://github.com/civiform/civiform/wiki/Authentication-Providers) for more details on your type of provider. * Domain name for your deployment. For example `civiform.mycity.gov` * ARN of an SSL certificate for load balancer. See [requesting AWS certificate](#requesting-aws-certificate) * Decision on how to organize your different CiviForm prod/staging/test instances. See [AWS deployment setup options](#aws-deployment-setup-options) ### Steps to run 1. Fork the [civiform-deploy](https://github.com/civiform/civiform-deploy) repo to your organization via the GitHub webpage. 2. Clone the repo onto the machine you are deploying from. 3. Find the version that you want to deploy on [Github](https://github.com/civiform/civiform/releases). 4. Copy the [`civiform_config.example.sh`](https://github.com/civiform/civiform-deploy/blob/main/civiform_config.example.sh) into `civiform_config.sh` and fill out the missing values. You should set all of the values appropriately for your environment, but the most important values are: * `CIVIFORM_MODE`: Set to `staging` for all instances except for your production instance which should be `prod`. * `CIVIFORM_VERSION`: Set this to the version string of the release you would like to deploy from [Github](https://github.com/civiform/civiform/releases), e.g. `v3.28.0`. Do not use `latest`, as this will be the latest development version and may be unstable. * `CIVIFORM_CLOUD_DEPLOYMENT_VERSION`: This is the version of the `cloud-deploy-infra` repo to check out to perform the deployment. This repo is tagged with the same version as CiviForm releases so that you can be sure you are using the version of the deployment system that was fully validated working with that version. This should always be set to `CIVIFORM_CLOUD_DEPLOYMENT_VERSION="${CIVIFORM_VERSION}"` unless directed otherwise by CiviForm staff to deploy a particular fix outside of a release. * `CIVIFORM_APPLICANT_AUTH_PROTOCOL`: Set to `oidc` or `saml` depending on your auth provider. * `CIVIC_ENTITY_LOGO_WITH_NAME_URL`, `CIVIC_ENTITY_SMALL_LOGO_URL`, and `FAVICON_URL` should point to publicly accessible files used to brand your instance. * `BASE_URL`: The URL of your civiform instance. * `AWS_REGION`: Set this to the region closest to your jurisdiction for best performance. * `APP_PREFIX`: If deploying multiple instances into the same AWS account (i.e. not separate accounts within an AWS Organization), they will each need to have a different app prefix so their resources do not conflict. * `SSL_CERTIFICATE_ARN`: This should be copied from the information for the SSL certificate created in AWS that is verified with your DNS provider. * The values in the `generic-oidc` and/or `ADFS and Azure AD configuration` sections according to your auth provider. 1. Run `bin/doctor` and install the dependencies. 2. Run `bin/setup`. What to expect: * Takes up to 20 minutes to run. Make sure you have time to allow the script to run to completion to avoid errors. * Terraform brings up resources in the cloud (database, network, server, etc). * Asks confirmation a few times before creating resources, listing everything that will be created. * Safe to re-run the script if it fails (re-runs will take longer because resources must be destroyed before being re-created). The configuration values in `civiform_config.sh` represent the desired state of your CiviForm deployment. The `bin/setup` and `bin/deploy` commands work to make your cloud environment match the desired state. If a command fails, your cloud environment may not match the desired state. These commands are safe to retry if they fail. If a command is persistently failing, you can work with our on-call engineer to resolve the issue. Our on-call engineer responds to new issues in the CiviForm issue tracker (see the on-call guide for details). Note: If you are running `bin/doctor` or another command for a config file other than `civiform_config.sh`, you can specify that with the config flag (i.e. `bin/doctor --config=civiform_staging_config.sh`) ## Deploy 1. Find the version that you want to deploy on [Github](https://github.com/civiform/civiform/releases). 2. Update the `CIVIFORM_VERSION` value in `civiform_config.sh`. 3. Run `bin/deploy`. ## Rotating the application secret The Play Framework used by CiviForm utilizes an [application secret key](https://www.playframework.com/documentation/3.0.x/ApplicationSecret). This key is used for signing session cookies and CSRF tokens, among other things. While this secret is stored securely by the deployment system, it's a good idea to rotate it periodically in order to mitigate the risk of a leaked secret. IMPORTANT: When the secret is rotated, all user sessions will be invalidated. This means that any guest users in the middle of an application that have not submitted it yet will lose that application, and any logged in users or admins will get logged out. It is recommended that this rotation happen at a low traffic time of day. You may also want to give users a warning before it happens. To rotate the secret, run `bin/run`, and enter the `rotate_app_secret` command. This will redeploy CiviForm, changing the secret key to a new, random value. Additionally, you should add `export RANDOM_PASSWORD_LENGTH=64` to your `civiform_config.sh` file. The secret length was originally only 16 characters. CiviForm uses Play Framework 3.x, which requires a minimum length of 32 characters. ## Troubleshooting #### Terraform fails with error "Provider produced inconsistent final plan" This error can happen when running `bin/setup` for the first time. If you see it, re-run `bin/setup`. This is a known Terraform [bug](https://github.com/hashicorp/terraform-provider-aws/issues/19583). #### Terraform fails with other errors The deploy command is idempotent, so if it fails, try running it again. The setup command can also be re-run, but it may fail to destroy resources if the resources Terraform uses to track created resources are corrupted. If the script is failing to destroy resources, try running `bin/run destroy` on its own. If this fails, you may need to manually delete resources in your cloud provider's console. Once all resources are cleaned up, run `bin/run destroy_backend_state_resources` to cleanup up the corrupted backend state resources and then try running `bin/setup` again. If changes were made upstream, you can change the code in the checkout env, but will need to commit PRs to fix in the main repo. #### No such file or directory If you see error like "no such file or directory" ``` ./db-connection: line 2: cloud/aws/bin/lib.sh: No such file or directory ./db-connection: line 21: out::error: command not found ``` The scripts expect you to be in specific directories. You probably need to `cd` into the checkout directory or the top level directory. If you are running `setup`/`deploy`, you will need to be in the top level directory. If you are running a script like `db-connection`, you need to be in the checkout directory. #### Terraform fails with `Error acquiring the state lock` This situation can happen when exiting deployment scripts using "Ctrl-C". Terraform acquires a lock every time you run `./bin/deploy` or `./bin/setup`, and releases the lock at the end of the script. This helps to prevent concurrent infrastructure changes. If the deploy process exited outside of Terraform, the lock remains and needs to be force removed in order to run deploy again. The end of the error message will contain the `LOCK_ID`. To unlock, re-run either `bin/deploy` or `bin/setup` with `FORCE_UNLOCK_ID` set like this: ``` FORCE_UNLOCK_ID="$LOCK_ID" ./bin/deploy ``` Alternatively, it can be done by manually calling terraform like this: ``` terraform -chdir=checkout/cloud/aws/templates/aws_oidc force-unlock $LOCK_ID ``` #### (AWS) Notes on using CloudShell for deployment It is an option to use CloudShell for doing deployments, but you should be aware that installations aren't persisted (see [FAQs](https://aws.amazon.com/cloudshell/faqs/)), so it may be easier to use the AWS CLI. If you do choose to use CloudShell, you likely will need to install Java and Terraform. Java can be installed with `sudo yum install java` and terraform can be installed by following the [installation commands](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli#install-terraform) under `Linux` / `Amazon Linux`. ## Helpful resources ### Requesting AWS certificate Follow [official documentation](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html). After your certificate is ready and validated, copy the ARN from your console and put it into the `SSL_CERTIFICATE_ARN` variable in your `civiform_config.sh` ARN has format of arn:aws:acm::\:certificate/\ ![Screen Shot 2022-08-10 at 3 50 39 PM](https://user-images.githubusercontent.com/1741747/184037024-c7ed7537-cfc6-41e9-9b32-40f1b4d03341.png) ### AWS deployment setup options Before going through the AWS deployment, it is helpful to understand how you plan to manage various deployments, if you plan to create multiple instances of CiviForm (i.e. staging, prod, etc.). By default, each deployment will have its own prefix, which allows you to distinguish the different ones from each other, but [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) is a way of keeping deployments more separate from each other. Some benefits of using AWS environments are: * There is more separation between environments, which makes it easier to remove resources without worrying about causing any issues to another deployment environment * It is easier to see cost breakdowns by deployment A drawback to be aware of is that you'll have to create profiles in the AWS CLI and switch between the different profiles when doing deployments or, if using CloudShell, you'll have to do this in separate CloudShell for each environment. ### Access the database for emergency repair The CiviForm deployment system provides a mechanism for temporary and secure direct access to the production database via the [pgadmin](https://www.pgadmin.org/) For details on how to access the database with pgadmin visit the [Production Database Access](/it-manual/sre-playbook/production-database-access) page. # AWS Terraform deployment Information specific to CiviForm Terraform deploy scripts for AWS. For general information, see [Terraform deploy system](/it-manual/sre-playbook/initial-deployment/terraform-deploy-system). ## Infrastructure ![AWS System Diagram](https://user-images.githubusercontent.com/1741747/184951252-1a33c8c8-8a86-44ea-b39a-cebea71e7495.png) Created for CiviForm app: * VPC * Load balancer * Internet Gateway * NAT Gateway * Fargate ECS cluster * RDS with Postgres * S3 bucket Connected services * SES * Secrets Manager Supporting Infrastructure: * S3 bucket for Terraform backend state * CloudWatch export for logs ## Code and examples (AWS) The code that manages deployment can be found [here](https://github.com/civiform/cloud-deploy-infra/tree/main/cloud/aws). Our staging environment is at [staging-aws.civiform.dev](https://staging-aws.civiform.dev). Config for the staging environment is [here](https://github.com/civiform/civiform-staging-deploy/blob/main/aws_staging_civiform_config.sh). ## Troubleshooting After running the `setup` or `deploy` script, you can login to the [AWS ECS console](https://console.aws.amazon.com/ecs/v2/clusters) to check the status of CiviForm. Make sure to select correct region in the top right corner. You should see Cluster with app\_prefix-civiform name. Click on it and go to Tasks tab. If everything is going well you should see a task in the Running state. ![Screen Shot 2022-08-15 at 5 18 55 PM](https://user-images.githubusercontent.com/1741747/184758808-c1081316-7baf-45dc-9c76-a64594a9de5e.png) ### Inspecting task config You can see the task configuration by clicking on the Task definition tab, finding the latest revision, and opening the JSON tab. ![Screen Shot 2022-08-15 at 5 21 53 PM](https://user-images.githubusercontent.com/1741747/184758833-fce81bec-9f2c-49be-a102-2d5b38aa58dd.png) ### Inspecting logs You can see the logs on the task page by clicking into the specific task and selecting Logs. ![Screen Shot 2022-08-15 at 5 23 27 PM](https://user-images.githubusercontent.com/1741747/184758931-a8374a7a-d1dc-4308-8676-7617d4237d7a.png) Logs are also available in CloudWatch. Search for app\_prefix-civiformlogs group. ![Screen Shot 2022-08-15 at 5 26 42 PM](https://user-images.githubusercontent.com/1741747/184758880-f92b064b-658c-401e-ad71-175f64fde305.png) # Authentication setup CiviForm supports two different flows for authentication: * Applicant authentication - how residents and trusted intermediaries or community based organizations will log into CiviForm * Accessed by the "Log in" or "Create account" buttons at the top right of any page or in the middle of the home page * Examples providers include: Login.gov, Oracle IDCS, LoginRadius, Generic OIDC (i.e. Auth0 or Google Identity) * Admin authentication - how CiviForm administrators and program administrators log into CiviForm * Accessed by the "Are you an administrator? Admin login" prompt at the bottom of the home page * Example providers include: Okta and Microsoft Entra ID (formerly Azure AD) Choosing an authentication provider involves various considerations, including price, existing login providers used by other sites managed by the city, and ease of use for both the city staff and the people logging in. Once an authentication provider is chosen, it is not recommended that it is changed, since data associating an applicant to their applications would be lost. ## Authentication setup At a high level, most authentication setups will involve: 1. Some setup through the authentication provider's website 2. Adding configuration values into the config.sh file of the deployment 3. Updating AWS Secrets Manager with the client ID and secret values ### Admin authentication setup * Okta and generic OIDC: follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc) * Azure AD and ADFS : follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#configure-azure-ad) ### Applicant authentication setup * Generic OIDC: follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) * Auth0: follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-example-auth0) * Google Identity: follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-example-google-identity) * Login.gov: follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) * Login Radius: follow steps [here](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) # Email configuration CiviForm uses email to send notifications to program administrators, applicants, and for a few other functionalities. Email addresses are provided via the deployment configuration file or the Admin Settings Panel. Below is the list of different email addresses that are required and some recommendations on how to organize them. ## Email addresses **Support email address** Applicants see this email address in the footer of each page as a mailto link. This value should be set via the Admin Settings Panel `SUPPORT_EMAIL_ADDRESS`. **Sender email address** This email address is used as a sender for all notifications sent by the CiviForm. For example, notifications sent on new applications (sent to program admins) and program status changes (sent to applicants). Config variable is `SENDER_EMAIL_ADDRESS`. **Notifications recipients in staging**. These email addresses are used only in staging. Instead of sending email notifications to program admins, they are sent to the provided email addresses. Config variables: `STAGING_PROGRAM_ADMIN_NOTIFICATION_MAILING_LIST`, `STAGING_TI_NOTIFICATION_MAILING_LIST`, `STAGING_APPLICANT_NOTIFICATION_MAILING_LIST`. ## Emails in staging For simplicity, we recommend having a single email address for staging and use it in all the variables listed above. ## Emails in prod If your organization already contains a tech support email address, use it. Otherwise, you can create something like . For simplicity, you can use the same email as sender. That way, admins and applicants can reply to the email if they are having difficulties or questions about the notification they received. Remember that someone needs to regularly check the inbox for the email addresses used in CiviForm. ## AWS SES CiviForm uses the AWS Simple Email Service (SES) to send emails. To send emails from a certain address, a verified identity must be created for the address. There are two kinds of verified identities: email-verified and domain-verified. In a new deployment, SES starts in sandbox mode. While SES is in sandbox mode, it can only send emails to verified identities. **SES must be taken out of sandbox mode for prod deployment, otherwise it will not be able to send emails to applicants, program admins, and TIs.** Follow [these steps](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) to take SES out of sandbox mode. We create email-verified identities for each unique email specified by the server environment variables `SENDER_EMAIL_ADDRESS`, `STAGING_PROGRAM_ADMIN_NOTIFICATION_MAILING_LIST`, `STAGING_TI_NOTIFICATION_MAILING_LIST`, and `STAGING_APPLICANT_NOTIFICATION_MAILING_LIST`. After the initial deployment, AWS will send 'Email Address Verification Request' emails to each created identity. You must click the verification link in the email for the identity to be verified. This allows you to test email sending in staging deployments without taking SES out of sandbox mode. ### Using a no-reply email address for SENDER\_EMAIL\_ADDRESS If you wish to use a no-reply address with no ability to receive emails, there are two options: 1. Configure the no-reply address so that it can receive emails before the first deployment, deploy CiviForm, click the verification link in the 'Email Address Verification Request' email sent to the no-reply address, then configure the no-reply address to not receive any emails. 2. Create a domain-verified SES identity. For example, to use '', you must create a domain-verified identity for 'mystate.gov'. Follow the steps in the 'Creating a domain identity' section of [this guide](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html). To verify the domain, you will need to add CNAME records in your domain registrar. ## Testing emails After deploying CiviForm to staging or prod it's important to test that email integration works correctly. Here is the list of things to try: 1. Open the CiviForm site as an applicant and send email to the technical support email address provided in the footer. 2. Create a program with a status that has email content. 3. Apply as an applicant. 4. Program Admin and applicant (and TI if present) should receive the email. 5. As a Program Admin, view the application and set the status. 6. The applicant (and TI if present) should receive the email. ## Troubleshooting SES email issues 1. Go to Simple Email Service in the AWS console * On the "Get Set Up" page, ensure production mode is enabled. Without production mode enabled, emails can only be sent from verified domains and there is a limit to the number of emails that can be sent * On the "Identities" page, ensure the identities are verified. You can use a specific email identity or a domain. 2. Check the ECS logs * If the ECS logs have a `Email address is not verified.` error, please go through the steps above. # GIS Service configuration You may have some programs that need to collect an applicant's address to offer services. Those programs may also want to verify that the address exists and matches a standard format, and may also want to verify that the address is in the area that's eligible for the program. For example, a program may only be for applicants living in a certain county. CiviForm uses the external Esri service for both these use cases. CiviForm is not currently compatible with other geolocation services. If you'd like to use another geolocation service, please reach out to the engineering team. ## Address Correction Programs may want to have an applicant's address corrected so that they can verify the address exists and have all addresses in a standard format. This needs to be configured both at the deployment level and at a question level. If you want to see what results address correction might provide, you can experiment with ArcGIS's world endpoint. [Here's a sample query for 700 5th Ave, Seattle WA 98101](https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?Address=700+5th+Ave\&City=Seattle\&Region=WA\&Postal=98101\&f=pjson). For your official deployment, you could choose to [use this endpoint](https://www.postman.com/esridevs/workspace/arcgis-location-services/request/15786767-3c13e739-ad89-496d-9ddd-7746b2335dd0) instead of defining your own, but you would still need to purchase an Esri subscription and create an Esri API token. ### Deployment-level configuration Before any specific program can use address correction, it must be enabled for your deployment as a whole. 1. Set [ESRI\_ADDRESS\_CORRECTION\_ENABLED](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L725) to true. 2. Set [ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS](https://github.com/civiform/civiform/blob/b7c2f30e0870ac2d9f798bc91d5153e10ec5ed64/server/conf/helper/esri.conf#L19) to one or more URLs that CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). The service should have a `GeocodeServer` type. Example URL value: "" {% hint style="info" %} Make sure the URL ends in `findAddressCandidates` {% endhint %} {% hint style="info" %} If you are using Esri's ArcGis Online service (arcgis.com), you need to also set a valid api token for [ESRI\_ARCGIS\_API\_TOKEN](https://github.com/civiform/civiform/blob/b7c2f30e0870ac2d9f798bc91d5153e10ec5ed64/server/conf/helper/esri.conf#L29). You can get a token via your arcgis.com account. {% endhint %} 3. Optional, but recommended. Set [ESRI\_WELLKNOWN\_ID\_OVERRIDE](https://github.com/civiform/civiform/blob/478246036fb280e5d9032c64f1dc4eedf1b088f6/server/conf/helper/esri.conf#L20) which forces the service calls to return spatial references using the specified wellknown id value for their coordinate system. #### Expected `findAddressCandidates` response format Civiform expects a response with the following fields: ```json { "spatialReference": { "wkid": 4326 }, "candidates": [ { "address": "555 Example St, Sample Town, AR, 55555", "location": { "x": -100.00, "y": 100.00 }, "score": 99.53, "attributes": { "SubAddr": "", "Address": "555 Example St", "City": "Sample Town", "Region": "", "RegionAbbr": "AR", "Postal": "55555" } }, {...}, {...} ] } ``` Notes on parsing: * If the response does not include a value in `SubAddr`, CiviForm keeps the value the user entered. * If the value in `RegionAbbr` is not two characters, CiviForm checks the `Region` field for the two character state code. If it's also not two characters, CiviForm keeps the state code the user provided. ### Overriding the default wellKnownId The Esri API has the ability to return spatial reference data using different coordinate systems via a wellKnownId (a.k.a wkid). Details of that along with links to the long list of possible coordinate systems can be found on the [arcgis developer site](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). The default wellKnownId is `4326 - GPS` which are traditional latitude and longitude values most often associated with coordinate systems. Custom hosted installations may set a different value as their default. For example, Seattle defaults to using wellKnownId `2926 - NAD_1983_HARN_StatePlane_Washington_North_FIPS_4601_Feet` [link](https://developers.arcgis.com/rest/services-reference/enterprise/pdf/pcs_PDF_11.2.pdf). This works fine as long as calls to correct an address and calls to mapping layers for service area validation are all defaulting to the same wellKnownId. Such as calling both endpoints on the same hosted instance. Where it becomes a problem is if you want to start mixing calls to different installations. #### Example > 1. Call arcgis.com to correct address, returns coordinates using wellKnownId 4326 > 2. Call Seattle's hosted instance for map query endpoints for service area validation using values from arcgis.com would result in not being eligible because the coordinates systems don't match By setting the ESRI\_WELLKNOWN\_ID\_OVERRIDE we force both systems to use the same coordinate system. #### Existing data After we get the corrected address we save the x, y, and wkid as part of the address. Calls to map query endpoints already use the stored wkid to specify what the input spatial reference should be. Existing records will still work as is. {% hint style="warning" %} If this override is added after CiviForm users have been using address correction and is different from the previously used default you will end up having new records stored in different format. If that is a concern the solution is to make sure the override value is the same as used before. This is only an issue if you change the find address endpoint at a later point in time to one with a different default. Such as using Seattle's version to using arcgis.com. If there is only a single host this will never be a problem since they'll both have the same defaults. {% endhint %} ### Applying to questions Once those configuration variables are set up, address correction can be enabled or disabled on any address question using a toggle: ![Image of address correction toggle enabled](/files/kbfGE8rFXLAE5itXicOc) When a user fills out an address question with address correction, CiviForm will use the Esri endpoint to fetch address suggestions. If a suggestion perfectly matches what the user inputted, the suggestion will automatically be used and the user will proceed with the application. Otherwise, the user will be presented with a screen asking them to choose the correct suggested address: ![Image of address correction page applicants will see](/files/fpOD51fesO5JA3SreW3s) Note that for each block in an application, there can only be one address question with address correction enabled. This is because it's complicated to chain multiple address correction pages together (both from a technical standpoint and from the perspective of an applicant). If multiple address questions need address correction, they can be on different blocks. ## Service Area Validation Service area validation checks whether an address is within a specific area. This can be used for visibility or eligibility conditions. For example, a user may only be eligible for a program if they live in a specific neighborhood. Service area validation requires that address correction must also be enabled for the question. CiviForm needs the address's latitude and longitude values from Esri to determine if the address is within a certain area, and we only get the latitude and longitude values from Esri's address correction information. ### Deployment-level configuration #### Step 1: Enable feature flag Set [ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L729) to true. Note that `ESRI_ADDRESS_CORRECTION_ENABLED` must also be set to true. #### Step 2: Configure service area map values Set the four `ESRI_ADDRESS_SERVICE_AREA_VALIDATION_*` configuration variables to contain the necessary information: * [ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L732) is the list of URL(s) that CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) to determine if the address is within the area specified by the map query service. The map should be a `MapService` type. * Type: String\[] * Example value: \[""] * [ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L730) is the list of labels that CiviForm admins will see when setting up eligibility or visibility conditions. * Type: String\[] * Example values: \["Seattle"], \["Abc County", "Def County", "Ghi County"] * [ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L733) is the list of attributes that should be checked in the response returned from the Esri service URL. Note that these attributes are custom for each Esri URL and you'll need to look at what fields are provided for your specific map to know what attribute to use. For example, [Seattle's service area validation service](https://gisdata.seattle.gov/server/rest/services/COS/Seattle_City_Limits/MapServer/1) specifies "CITYNAME" as an attribute. * Type: String\[] * Example values: \["CITYNAME"], \["ZIPCODE"] * [ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L731) is the list of values that the attribute should be equal to in order for the address to be considered within the service area. * Type: String\[] * Example values: * If `_ATTRIBUTES` is set to \["CITYNAME"], then `_IDS` could be set to \["Seattle"] in order to require addresses be in the city of Seattle. * If `_ATTRIBUTES` is set to \["ZIPCODE"], then `_IDS` could be set to \["28202"] in order to require addresses be in the 28202 zip code. The configuration allows you to set up multiple service areas so that different questions can have different eligibility requirements. For example, maybe one program allows anyone in the county to apply while a different program only allows people in a certain zip code to apply. You can set up two service areas: ``` export ESRI_ADDRESS_SERVICE_AREA_VALIDATION_URLS = ["arkansas-url", "neighborhood-url"] export ESRI_ADDRESS_SERVICE_AREA_VALIDATION_LABELS = ["Arkansas", "Example Neighborhood"] export ESRI_ADDRESS_SERVICE_AREA_VALIDATION_ATTRIBUTES = ["STATE", "ZIPCODE"] export ESRI_ADDRESS_SERVICE_AREA_VALIDATION_IDS = ["AR", "01234"] ``` One program can set their eligibility condition to use "Arkansas" and the other program can set their eligibility condition to use "Example Neighborhood". The arrays in each of these four variables should all be the same length. The values at index `i` should all correlate with each other. In the example above, all values at index `0` are for checking the county service area, and all values at index `1` are for checking the neighborhood service area. Put another way: * When checking that an address is in the service area labeled "Arkansas" in the admin UI, CiviForm will query `arkansas-url` and check the response for a field called `STATE` with a value of "AR". * When checking that an address is in the service area labeled "Example Neighborhood" in the admin UI, CiviForm will query `neighborhood-url` and check the response for a field called `ZIPCODE` with a value of "01234". ### Applying to questions Once those configuration variables are set up, service area validation can be enabled or disabled on any address question using eligibility or visibility conditions: ![Image of validating that an address is in the Seattle service area as an eligibility condition](/files/7Jx4iDxU7cZ2FO0bo8GD) Address correction must be enabled on the question before the eligibility or visibility conditions based on the service area can be set up. ## Other configuration [ESRI\_EXTERNAL\_CALL\_TRIES](https://github.com/civiform/civiform/blob/fd0aaa002e2ee01d378ca90f236c316641ed0101/server/conf/application.conf#L735) - Integer The number of tries CiviForm will attempt requests to external Esri services. # Upgrading to a New Release The CiviForm core team [distributes new versions of the system](https://github.com/civiform/civiform/releases) every other week on Tuesdays or Wednesdays. We strongly recommend deployments stay up to date with the latest version to benefit from security patches, bug fixes, and new features. Each release is published using [GitHub releases](https://github.com/civiform/civiform/releases) with a corresponding server Docker image uploaded to [civiform/civiform on Docker Hub](https://hub.docker.com/r/civiform/civiform) and tagged with the release number. **Be sure to review the release notes on GitHub for each new release before deploying it.** Release notes include: * Description of fixed bugs and security vulnerabilities * Description of new features * Database schema changes * Other stateful changes (such as stored file key name schema) * API version changes and deprecation notices * New configuration values * Infrastructure changes * Dependency changes (for the server only) including new, removed, and version updates New releases are also announced on [civiform-announce@googlegroups.com](https://groups.google.com/g/civiform-announce) ## Version numbers Version numbers take the form `v..`. Generally, we will always increment the minor version with each release and set the patch version to 0. If we do an unscheduled release in order to fix a bug, we'll increment the patch version. The major version will only increment if the release includes changes that require great care when deploying or includes significant changes to the way CiviForm works. ### Major version A new major version indicates major feature or functionality changes that could be disruptive to users or administrators of the system without preparation (i.e. a chance for staff to read documentation or get an overview of new UI). A new major version must be created if there are any changes that cannot be deployed by simply updating the server image, but also require manual technical staff effort from downstream deployments to incorporate. Examples of this kind of effort include altering deployment infrastructure, moving to a new major PostgreSQL version, etc. In general, the CiviForm core team seeks to minimize effort needed by downstream maintainers to perform version upgrades. A new major version may also be created when there are significant changes to CiviForm functionality or appearance. Admins should ensure they have database backups before applying a new major change. ### Minor version A new minor version indicates feature or functionality changes that enable new capabilities in the system or fix existing ones, but are unlikely to be disruptive and do not require significant preparation. Examples of such changes include new features, new APIs or API versions, new configuration parameters, and new resources in the system. A new minor version may also indicate changes in the database schema, file key naming schema, or other stateful parts of the application. New minor versions should be deployable by simply updating the server image (the Play Framework evolutions system should update the database schema automatically). Admins should ensure they have database backups before applying a new minor change. ### Patch version A new patch version indicates a bug fix to the previous release that was serious enough to require an unscheduled release. Patch versions should generally be taken up as soon as possible, but if the bug fixed does not apply to your environment, waiting until the next release may be viable. # CiviForm server environment variables The CiviForm server is configurable through environment variables. All available variables are documented in a [env-var-docs.json](https://github.com/civiform/civiform/blob/main/server/conf/env-var-docs.json) file in the civiform/civiform repository. When a CiviForm server version is released, the env-var-docs.json file corresponding to the release is used to generate markdown documentation of the variables. The generated markdown files are added to this directory. Use the left sidebar to see the available configuration variables for the CiviForm version you are deploying. Variables can have four different modes which determine where they are set and displayed: 1. "Admin writeable" variables should be set in the admin settings panel which is accessible in CiviForm when logged in as an admin. These variables should NOT be set in your deployment config and setting them there will result in a deployment error. If you need to set custom values for Admin writeable variables during an initial deploy, it is possible to override this error by setting `export ALLOW_ADMIN_WRITEABLE=true` in your deploy config. This should only be used for the initial deploy and should be removed from the config immediately afterwards. 2. "Admin readable" variables should be set in your deployment config file. The values for these variables can be seen in the admin settings panel, but not changed there. 3. "Server setting" variables should be set in your deployment config file and are not visible in the admin settings panel. 4. "Managed secret" variables should be set in your cloud provider's secrets manager. These are not visible in the admin settings panel. A variable's mode is listed in between the variable name and its description in the server environment variable documentation that is generated on each release and saved in this directory (for example [v3.27.0](https://docs.civiform.us/it-manual/sre-playbook/server-environment-variables/v3.27.0)). # v2.34.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** The hex code value of the color to use as the primary branding color of the website. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** The hex code value of the color to use as the primary-dark branding color of the website. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### DISABLED\_VISIBILITY\_CONDITION\_ENABLED **Admin writeable** Enables the feature that allows programs to be disabled from CiviForm * Type: bool ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### FASTFORWARD\_ENABLED **Admin writeable** When enabled, existing draft applications will automatically be updated to use the latest version of a program when a newer version has been published. * Type: bool ### BULK\_STATUS\_UPDATE\_ENABLED **Admin writeable** When enabled, admins will be able to select many applications for status updates * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool # v2.35.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** The hex code value of the color to use as the primary branding color of the website. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** The hex code value of the color to use as the primary-dark branding color of the website. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### FASTFORWARD\_ENABLED **Admin writeable** When enabled, existing draft applications will automatically be updated to use the latest version of a program when a newer version has been published. * Type: bool ### BULK\_STATUS\_UPDATE\_ENABLED **Admin writeable** When enabled, admins will be able to select many applications for status updates * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool # v2.36.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** The hex code value of the color to use as the primary branding color of the website. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** The hex code value of the color to use as the primary-dark branding color of the website. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### FASTFORWARD\_ENABLED **Admin writeable** When enabled, existing draft applications will automatically be updated to use the latest version of a program when a newer version has been published. * Type: bool ### BULK\_STATUS\_UPDATE\_ENABLED **Admin writeable** When enabled, admins will be able to select many applications for status updates * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool # v2.37.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `^#(?:[0-9a-fA-F]{3}){1,2}$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v2.38.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v2.39.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v2.40.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v2.41.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables filtering programs by category on the homepage * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** (NOT FOR PRODUCTION USE) Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable using custom theme colors on North Star applicant UI. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v3.0.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. Not ready for production use. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when things break. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v3.1.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool # v3.2.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool # v3.3.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin writeable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool # v3.4.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin readable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables suffix dropdown field in name question. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool # v3.5.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin readable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin writeable** Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables admin validation settings for date questions. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool # v3.6.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin readable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin readable** Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables admin validation settings for date questions. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool # v3.7.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin readable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin readable** Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables admin validation settings for date questions. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool # v3.8.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### PROGRAM\_FILTERING\_ENABLED **Admin readable** Enables filtering programs by category on the homepage * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin readable** Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** Enables admin validation settings for date questions. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### NO\_DUPLICATE\_QUESTIONS\_FOR\_MIGRATION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Ensures duplicate questions aren't created when migrating programs between deployed environments. Note: this should only be used on new environments, since existing programs will be modified if a program with the same question gets imported. * Type: bool ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool # v3.9.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### IMPORT\_DUPLICATE\_HANDLING\_OPTIONS\_ENABLED **Admin readable** Enable options for handling duplicate questions when importing/migrating programs: create a duplicate, use the existing question, or overwrite the existing question. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** Enables admin validation settings for date questions. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool # v3.10.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** Enables admin validation settings for date questions. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool # v3.11.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** Enables admin validation settings for date questions. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool # v3.12.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** Enables admin validation settings for date questions. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool # v3.13.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin writeable** Enables admin validation settings for date questions. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool # v3.14.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin writeable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin readable** Enables admin validation settings for date questions. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool # v3.15.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin readable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin readable** Enables admin validation settings for date questions. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool # v3.16.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin readable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin readable** Enables admin validation settings for date questions. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool # v3.17.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin writeable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin readable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### DATE\_VALIDATION\_ENABLED **Admin readable** Enables admin validation settings for date questions. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### MAP\_QUESTION\_ENABLED **Server setting** (NOT FOR PRODUCTION USE) Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool # v3.18.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin readable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin writeable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool # v3.19.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. Since northstar hides the logo on smaller screens, this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### NORTH\_STAR\_APPLICANT\_UI **Admin readable** Enables showing new UI with an updated user experience in Applicant flows * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors on North Star applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin writeable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards on North Star applicant UI. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool # v3.20.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Common Intake confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### API\_GENERATED\_DOCS\_ENABLED **Admin writeable** Enables the API docs tab on CiviForm. * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin writeable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enables reading settings from the cache instead of directly from the database. * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool # v3.21.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin writeable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** Enables reading settings from the cache instead of directly from the database. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable showing external program cards. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool # v3.22.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin writeable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** Enables reading settings from the cache instead of directly from the database. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new dropdown for login that has both applicant and admin login. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool # v3.23.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ### IMMIGRATION\_STATUS\_INFO\_BANNER\_LEARN\_MORE\_URL **Admin writeable** The HREF for providing more information for the immigration status informational banner. * Type: string ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin readable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** Enables reading settings from the cache instead of directly from the database. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** Enables a dropdown for login that has both applicant and admin login. * Type: bool ### IMMIGRATION\_STATUS\_INFO\_BANNER\_ENABLED **Admin writeable** Enable showing an immigration status informational banner to applicants. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. Inactivity timeout is always enforced when enabled. Maximum duration enforcement additionally requires SESSION\_REPLAY\_PROTECTION\_ENABLED=true. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_EXTENDED\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable extended options in the admin UI migration in Thymeleaf. * Type: bool # v3.24.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ### IMMIGRATION\_STATUS\_INFO\_BANNER\_LEARN\_MORE\_URL **Admin writeable** The HREF for providing more information for the immigration status informational banner. * Type: string ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### MAP\_QUESTION\_ENABLED **Admin readable** Enable allowing CiviForm admins to add a map question to their programs. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### SETTINGS\_CACHE\_ENABLED **Admin readable** Enables reading settings from the cache instead of directly from the database. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** Enables a dropdown for login that has both applicant and admin login. * Type: bool ### IMMIGRATION\_STATUS\_INFO\_BANNER\_ENABLED **Admin writeable** Enable showing an immigration status informational banner to applicants. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. Inactivity timeout is always enforced when enabled. Maximum duration enforcement additionally requires SESSION\_REPLAY\_PROTECTION\_ENABLED=true. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_EXTENDED\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable extended options in the admin UI migration in Thymeleaf. * Type: bool # v3.25.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ### IMMIGRATION\_STATUS\_INFO\_BANNER\_LEARN\_MORE\_URL **Admin writeable** The HREF for providing more information for the immigration status informational banner. * Type: string ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### SESSION\_REPLAY\_PROTECTION\_ENABLED **Admin readable** Enable session replay protection, so that a session cookie cannot be replayed if the user logs out * Type: bool ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** Enables a dropdown for login that has both applicant and admin login. * Type: bool ### IMMIGRATION\_STATUS\_INFO\_BANNER\_ENABLED **Admin writeable** Enable showing an immigration status informational banner to applicants. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. Inactivity timeout is always enforced when enabled. Maximum duration enforcement additionally requires SESSION\_REPLAY\_PROTECTION\_ENABLED=true. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_EXTENDED\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable extended options in the admin UI migration in Thymeleaf. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable the new applicant-guest merging strategy. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_DRY\_RUN\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable dry run logging for the new applicant-guest merging strategy. * Type: bool # v3.26.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ### IMMIGRATION\_STATUS\_INFO\_BANNER\_LEARN\_MORE\_URL **Admin writeable** The HREF for providing more information for the immigration status informational banner. * Type: string ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** Enables a dropdown for login that has both applicant and admin login. * Type: bool ### IMMIGRATION\_STATUS\_INFO\_BANNER\_ENABLED **Admin writeable** Enable showing an immigration status informational banner to applicants. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### FILE\_UPLOAD\_QUESTION\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which allow for file upload questions on the same page as other question types. Uses a new file upload method that uploads applicant files through CiviForm servers. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_EXTENDED\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable extended options in the admin UI migration in Thymeleaf. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable the new applicant-guest merging strategy. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_DRY\_RUN\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable dry run logging for the new applicant-guest merging strategy. * Type: bool # v3.27.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ### IMMIGRATION\_STATUS\_INFO\_BANNER\_LEARN\_MORE\_URL **Admin writeable** The HREF for providing more information for the immigration status informational banner. * Type: string ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** Enables a dropdown for login that has both applicant and admin login. * Type: bool ### IMMIGRATION\_STATUS\_INFO\_BANNER\_ENABLED **Admin writeable** Enable showing an immigration status informational banner to applicants. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable session timeout based on inactivity and maximum duration. * Type: bool ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### FILE\_UPLOAD\_QUESTION\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which allow for file upload questions on the same page as other question types. Uses a new file upload method that uploads applicant files through CiviForm servers. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_EXTENDED\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable extended options in the admin UI migration in Thymeleaf. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable the new applicant-guest merging strategy. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_DRY\_RUN\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable dry run logging for the new applicant-guest merging strategy. * Type: bool # v3.28.0 ## Branding Configuration options for CiviForm branding. ### CIVIC\_ENTITY\_SMALL\_LOGO\_URL **Admin readable** Small logo for the civic entity used on the login page. **Required**. * Type: string ### CIVIC\_ENTITY\_FOOTER\_LOGO\_URL **Admin readable** Logo for the civic entity used in the footer. If not set, falls back to CIVIC\_ENTITY\_SMALL\_LOGO\_URL. * Type: string ### WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME **Admin writeable** The short display name of the civic entity, will use 'TestCity' if not set. **Required**. * Type: string ### HIDE\_CIVIC\_ENTITY\_NAME\_IN\_HEADER **Admin writeable** Whether the WHITELABEL\_CIVIC\_ENTITY\_SHORT\_NAME should be hidden in the CiviForm header. This may be desired if the government name is included in the logo. The logo is hidden on smaller screens, so this will only hide the name if the logo is showing. * Type: bool ### WHITELABEL\_CIVIC\_ENTITY\_FULL\_NAME **Admin writeable** The full display name of the civic entity, will use 'City of TestCity' if not set. **Required**. * Type: string ### CIVIC\_ENTITY\_PRODUCTION\_URL **Admin writeable** The URL to the civic entity's production CiviForm site. * Type: string ### FAVICON\_URL **Admin readable** The URL of a 32x32 or 16x16 pixel [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) image, in GIF, PNG, or ICO format. * Type: string ### THEME\_COLOR\_PRIMARY **Admin writeable** A primary color is the color displayed most prominently across your website. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ### THEME\_COLOR\_PRIMARY\_DARK **Admin writeable** A darker version of your primary color can be applied to your website for some purposes. Enter the hex code for this color. * Type: string * Validation regular expression: `(^#(?:[0-9a-fA-F]{3}){1,2}$)|^$` * Regular expression examples: * `#f12345` should match. * `#c13` should match. * `cccccc` should not match. * \`\` should match. ## External Services Configures connections to external services the CiviForm server relies on. ### Applicant Identity Provider Configuration options for the [applicant identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#applicant-authentication). #### CIVIFORM\_APPLICANT\_IDP **Admin readable** What identity provider to use for applicants. **Required**. * Type: string * Allowed values: * `idcs` * `login-radius` * `generic-oidc` * `login-gov` * `auth0` * `disabled` #### APPLICANT\_REGISTER\_URI **Admin readable** URI to create a new account in the applicant identity provider. * Type: string #### APPLICANT\_PORTAL\_NAME **Admin writeable** The name of the portal that applicants log into, used in sentences like 'Log into your APPLICANT\_PORTAL\_NAME account.' **Required**. * Type: string #### Oracle Identity Cloud Service Configuration options for the [idcs](https://github.com/civiform/civiform/wiki/Authentication-Providers#oracle-idcs) provider. **IDCS\_CLIENT\_ID** **Managed secret** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client. * Type: string **IDCS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **IDCS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string #### Login Radius Configuration options for the [login-radius](https://github.com/civiform/civiform/wiki/Authentication-Providers#loginradius-saml) provider **LOGIN\_RADIUS\_API\_KEY** **Server setting** The API key used to interact with LoginRadius. * Type: string **LOGIN\_RADIUS\_METADATA\_URI** **Server setting** The base URL to construct SAML endpoints, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_SAML\_APP\_NAME** **Server setting** The name for the app, based on the SAML2 spec. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_NAME** **Server setting** Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth. * Type: string **LOGIN\_RADIUS\_KEYSTORE\_PASS** **Server setting** The password used the protect the integrity of the SAML keystore file. * Type: string **LOGIN\_RADIUS\_PRIVATE\_KEY\_PASS** **Server setting** The password used to protect the private key of the SAML digital certificate. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **APPLICANT\_OIDC\_PROVIDER\_LOGOUT** **Server setting** Enables [central logout](https://github.com/civiform/civiform/wiki/Authentication-Providers#logout-2) for both admin and applicant auth providers (despite the name). * Type: bool **APPLICANT\_OIDC\_OVERRIDE\_LOGOUT\_URL** **Server setting** By default the 'end\_session\_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL. * Type: string **APPLICANT\_OIDC\_POST\_LOGOUT\_REDIRECT\_PARAM** **Server setting** URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post\_logout\_redirect\_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout). * Type: string **APPLICANT\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”. * Type: string **APPLICANT\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **APPLICANT\_OIDC\_CLIENT\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **APPLICANT\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **APPLICANT\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **APPLICANT\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string **APPLICANT\_OIDC\_LOCALE\_ATTRIBUTE** **Server setting** The locale of the user, such as “en-US”. * Type: string **APPLICANT\_OIDC\_EMAIL\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s email address. * Type: string **APPLICANT\_OIDC\_FIRST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s first name. * Type: string **APPLICANT\_OIDC\_MIDDLE\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s middle name. * Type: string **APPLICANT\_OIDC\_LAST\_NAME\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s last name. * Type: string **APPLICANT\_OIDC\_NAME\_SUFFIX\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s name suffix. * Type: string **APPLICANT\_OIDC\_PHONE\_NUMBER\_ATTRIBUTE** **Server setting** The OIDC attribute name for the user’s phone number. * Type: string #### Login.gov Configuration options for the [login-gov](https://github.com/civiform/civiform/wiki/Authentication-Providers#logingov-oidc) provider **LOGIN\_GOV\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client. * Type: string **LOGIN\_GOV\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov. * Type: string **LOGIN\_GOV\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **LOGIN\_GOV\_ACR\_VALUE** **Server setting** [Authentication Context Class Reference requests](https://developers.login.gov/oidc/#request-parameters). ial/1 is for open registration, email only. ial/2 is for requiring identity verification. * Type: string * Allowed values: * `http://idmanagement.gov/ns/assurance/ial/1` * `http://idmanagement.gov/ns/assurance/ial/2` ### Administrator Identity Provider Configuration options for the [administrator identity provider](https://github.com/civiform/civiform/wiki/Authentication-Providers#admin-authentication). #### CIVIFORM\_ADMIN\_IDP **Admin readable** What identity provider to use for admins. * Type: string * Allowed values: * `adfs` * `generic-oidc-admin` #### Active Directory Federation Services Configuration options for the [ADFS](https://github.com/civiform/civiform/wiki/Authentication-Providers#azure-ad-and-adfs-oidc) provider. **ADFS\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client. * Type: string **ADFS\_SECRET** **Managed secret** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADFS\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider. * Type: string **ADFS\_ADMIN\_GROUP** **Server setting** The name of the admin group in Active Directory, typically used to tell if a user is a global admin. * Type: string **ADFS\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space. * Type: string **AD\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** The attribute name for looking up the groups associated with a particular user. * Type: string #### OpenID Connect Configuration options for the [generic-oidc](https://github.com/civiform/civiform/wiki/Authentication-Providers#generic-oidc-oidc) provider. **ADMIN\_OIDC\_PROVIDER\_NAME** **Server setting** The name of the OIDC (OpenID Connect) auth provider (server), such as 'Auth0' or 'Okta'. * Type: string **ADMIN\_OIDC\_CLIENT\_ID** **Server setting** An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client. * Type: string **ADMIN\_OIDC\_CLIENT\_SECRET** **Server setting** A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server. * Type: string **ADMIN\_OIDC\_DISCOVERY\_URI** **Server setting** A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider. * Type: string **ADMIN\_OIDC\_RESPONSE\_MODE** **Server setting** Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_RESPONSE\_TYPE** **Server setting** Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec. * Type: string **ADMIN\_OIDC\_USE\_CSRF** **Server setting** OIDC client should provide CSRF protection. * Type: bool **ADMIN\_OIDC\_ID\_GROUPS\_ATTRIBUTE\_NAME** **Server setting** Name of attribute that provides the groups associated with an account. * Type: string **ADMIN\_OIDC\_ADMIN\_GROUP\_NAME** **Server setting** Name of group that indicates an account is a global admin. * Type: string **ADMIN\_OIDC\_ADDITIONAL\_SCOPES** **Server setting** Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. * Type: string ### Database Configures the connection to the PostgreSQL database. #### DATABASE\_APPLY\_DESTRUCTIVE\_CHANGES **Server setting** If enabled, [playframework down evolutions](https://www.playframework.com/documentation/2.8.x/Evolutions#Evolutions-scripts) are automatically applied on server start if needed. * Type: bool #### DATABASE\_CONNECTION\_POOL\_SIZE **Server setting** Sets how many connections to the database are maintained. * Type: int #### DB\_JDBC\_STRING **Server setting** The database URL. * Type: string #### DB\_USERNAME **Managed secret** The username used to connect to the database. * Type: string #### DB\_PASSWORD **Managed secret** The password used to connect to the database. * Type: string ### Thread pools Configures the Play framework [thread pools](https://www.playframework.com/documentation/2.8.x/ThreadPools). #### AKKA\_DEFAULT\_EXECUTOR **Server setting** Determines which kind of ExecutorService to use for the default dispatcher. The default is 'fork-join-executor' * Type: string #### FORK\_JOIN\_PARALLELISM\_MIN **Server setting** Min number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_MAX **Server setting** Max number of threads to cap factor-based parallelism number to for the 'fork-join-executor' * Type: int #### FORK\_JOIN\_PARALLELISM\_FACTOR **Server setting** The parallelism factor is used to determine thread pool size for the 'fork-join-executor' using the following formula: ceil(available processors \* factor). Resulting size is then bounded by the parallelism-min and parallelism-max values. * Type: int #### THREAD\_POOL\_EXECUTOR\_FIXED\_POOL\_SIZE **Server setting** The size of the thread pool for the 'thread-pool-executor' type. If not defined, this will use the [default](https://github.com/akka/akka/blob/main/akka-actor/src/main/resources/reference.conf#L492) core and max pool sizes. * Type: int #### AKKA\_THROUGHPUT **Server setting** The number of messages that are processed in a batch before the thread is returned to the pool. Set to 1 for as fair as possible. * Type: int ### AWS\_REGION **Server setting** Region where the AWS SES service exists. If STORAGE\_SERVICE\_NAME is set to 'aws', it is also the region where the AWS s3 service exists. * Type: string ### GCP\_REGION **Server setting** The GCP Region. If STORAGE\_SERVICE\_NAME is set to 'gcp', it is also the region where the GCP s3 compatible service exists. * Type: string ### SENDER\_EMAIL\_ADDRESS **Server setting** The email address used for the 'from' email header for emails sent by CiviForm. **Required**. * Type: string ### EMAIL\_PROVIDER **Server setting** The provider to use for sending emails. * Type: string * Allowed values: * `aws-ses` * `graph-api` ### GRAPH\_API\_EMAIL\_ACCOUNT **Server setting** The email or account ID that graph API should use to send the email. * Type: string ### Application File Upload Storage Configuration options for the application file upload storage provider #### STORAGE\_SERVICE\_NAME **Server setting** What static file storage provider to use. * Type: string * Allowed values: * `s3` * `aws-s3` * `azure-blob` * `gcp-s3` #### AWS\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### AWS\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### AWS\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### AWS\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_NAME **Server setting** The azure account name where the blob storage service exists. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_CONTAINER\_NAME **Server setting** Azure blob storage container name to store public files in. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to Azure blob storage. * Type: string #### AZURE\_STORAGE\_ACCOUNT\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to Azure blob storage. * Type: string #### AZURE\_LOCAL\_CONNECTION\_STRING **Server setting** Allows local [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) to be used for developer deployments. * Type: string #### GCP\_S3\_BUCKET\_NAME **Server setting** s3 bucket to store files in. * Type: string #### GCP\_S3\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of files uploaded to s3. * Type: string #### GCP\_S3\_PUBLIC\_BUCKET\_NAME **Server setting** s3 bucket to store **publicly accessible** files in. * Type: string #### GCP\_S3\_PUBLIC\_FILE\_LIMIT\_MB **Server setting** The max size (in Mb) of **publicly accessible** files uploaded to s3. * Type: string ### ESRI Address Validation Configuration options for the ESRI GIS client and address validation/correction feature. #### Address Correction Address Correction Settings **ESRI\_ADDRESS\_CORRECTION\_ENABLED** **Admin writeable** Enables the feature that allows address correction for address questions. * Type: bool **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URL** **Admin readable** \[Deprecated: Switch to `ESRI_FIND_ADDRESS_CANDIDATES_URLS`] The URL CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). * Type: string **ESRI\_FIND\_ADDRESS\_CANDIDATES\_URLS** **Admin readable** The list of URLs CiviForm will use to call Esri’s [findAddressCandidates service](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm). These are used sequentially and not all of them may need to be used for every correction. If any results have a score of 90 or higher, lower priority urls will not be called. * Type: index-list #### Service Area Validation Service Area Validation Settings **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ENABLED** **Admin writeable** Enables the feature that allows for service area validation of a corrected address. ESRI\_ADDRESS\_CORRECTION\_ENABLED needs to be enabled. * Type: bool **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_LABELS** **Admin readable** Human readable labels used to present the service area validation options in CiviForm’s admin UI. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_IDS** **Admin readable** The value CiviForm uses to validate if an address is in a service area. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_URLS** **Admin readable** The URL CiviForm will use to call Esri’s [map query service](https://developers.arcgis.com/rest/services-reference/enterprise/query-feature-service-layer-.htm) for service area validation. * Type: index-list **ESRI\_ADDRESS\_SERVICE\_AREA\_VALIDATION\_ATTRIBUTES** **Admin readable** The attribute CiviForm checks from the service area validation response to get the service area validation ID. * Type: index-list #### General ESRI Settings **ESRI\_EXTERNAL\_CALL\_TRIES** **Admin readable** The number of tries CiviForm will attempt requests to external Esri services. * Type: int **ESRI\_WELLKNOWN\_ID\_OVERRIDE** **Admin readable** Forces calls to Esri services to use the specified spatial reference wellKnownId value for the [coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). If not set the default configuration from the Esri server is used. Setting this may be needed if using the results of the findAddressCandidates service return spatial references in a format different from one or more of the map query service endpoints. * Type: int **ESRI\_ARCGIS\_API\_TOKEN** **Server setting** A secret token value from Esri's arcgis.com online service created by your arcgis.com account for accessing the API. * Type: string ## Email Addresses Configuration options for [CiviForm email usage](https://docs.civiform.us/it-manual/sre-playbook/email-configuration). ### SUPPORT\_EMAIL\_ADDRESS **Admin writeable** This email address is listed in the footer for applicants to contact support. **Required**. * Type: string ### IT\_EMAIL\_ADDRESS **Admin readable** This email address receives error notifications from CiviForm when there is an internal server error or a durable job fails. * Type: string ### STAGING\_PROGRAM\_ADMIN\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address. **Required**. * Type: string ### STAGING\_TI\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address. **Required**. * Type: string ### STAGING\_APPLICANT\_NOTIFICATION\_MAILING\_LIST **Server setting** If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address. **Required**. * Type: string ## Custom Text Text specific to a civic entity. ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_TEXT **Admin writeable** The text for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string ### COMMON\_INTAKE\_MORE\_RESOURCES\_LINK\_HREF **Admin writeable** The HREF for a link on the Pre-Screener confirmation page that links to more resources. Shown when the applicant is not eligible for any programs in CiviForm. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ### IMMIGRATION\_STATUS\_INFO\_BANNER\_LEARN\_MORE\_URL **Admin writeable** The HREF for providing more information for the immigration status informational banner. * Type: string ## SECRET\_KEY **Managed secret** The [secret key](http://www.playframework.com/documentation/latest/ApplicationSecret) is used to sign Play's session cookie. This must be changed for production. * Type: string ## BASE\_URL **Admin readable** The URL of the CiviForm deployment. Must start with 'https\://' or 'http\://'. **Required**. * Type: string * Validation regular expression: `^(http://|https://).+` * Regular expression examples: * `http://my-civiform.org` should match. * `https://my-civiform.org` should match. * `my-civiform.org` should not match. ## STAGING\_HOSTNAME **Server setting** DNS name of the staging deployment. Must not start with 'https\://' or 'http\://'. * Type: string * Validation regular expression: `^(?!http://|https://).+` * Regular expression examples: * `my-civiform.org` should match. * `http://my-civiform.org` should not match. * `https://my-civiform.org` should not match. ## CIVIFORM\_SUPPORTED\_LANGUAGES **Server setting** The full list of languages available to CiviForm. These are the language that admins can choose from when adding translations for programs and applications, as well as the default list that applicants can choose from when specifying their language preference. See CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES for further control over languages available to applicants. * Type: index-list ## CIVIFORM\_APPLICANT\_ENABLED\_LANGUAGES **Server setting** If populated, this filters the languages that are visible to the applicant to just those in the list. This allows program admins to develop languages support for programs and questions, but not let the applicant use a language that is not yet ready. * Type: index-list ## CIVIFORM\_TIME\_ZONE\_ID **Admin readable** A Java [time zone ID](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html) indicating the time zone for this CiviForm deployment. All times in the system will be calculated in this zone. Default value is 'America/Los\_Angeles' **Required**. * Type: string ## CIVIFORM\_IMAGE\_TAG **Admin readable** The tag of the docker image this server is running inside. Is added as a HTML meta tag with name 'civiform-build-tag'. * Type: string ## CIVIFORM\_VERSION **Admin readable** The release version of CiviForm. For example: v1.18.0. * Type: string ## ALLOWED\_IP\_ADDRESSES\_FOR\_LOGOUT **Admin readable** IP addresses that are allowed to logout a user through the /logoutAllSessions endpoint. If configured, this will normally be the IP address(es) of the authentication provider. If not specified, all IP addresses are allowed. * Type: index-list ## CLIENT\_IP\_TYPE **Admin readable** Where to find the IP address for incoming requests. Default is "DIRECT" where the IP address of the request is the originating IP address. If "FORWARDED" then request has been reverse proxied and the originating IP address is stored in the X-Forwarded-For header. * Type: string * Allowed values: * `DIRECT` * `FORWARDED` ## NUM\_TRUSTED\_PROXIES **Admin readable** The count of reverse proxies between the internet and the server. In typical deployments, this value is 1. * Type: int ## FILE\_UPLOAD\_ALLOWED\_FILE\_TYPE\_SPECIFIERS **Admin readable** Specifies the allowed file types that can be uploaded. Uses any valid [file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Multiple are separated by commas. Default: "image/\*,.pdf" * Type: string ## Observability Configuration options for CiviForm observability features. ### CIVIFORM\_SERVER\_METRICS\_ENABLED **Admin readable** If enabled, allows server Prometheus metrics to be retrieved via the '/metrics' URL path. If disabled, '/metrics' returns a 404. * Type: bool ### MEASUREMENT\_ID **Admin readable** The Google Analytics tracking ID. If set, Google Analytics JavaScript scripts are added to the CiviForm pages. * Type: string ## Data Export API Configuration options for the [CiviForm API](https://docs.civiform.us/it-manual/api). ### CIVIFORM\_API\_SECRET\_SALT **Managed secret** A cryptographic [secret salt](https://en.wikipedia.org/wiki/Salt_\(cryptography\)) used for salting API keys before storing their hash values in the database. This value should be kept strictly secret. If one suspects the secret has been leaked or otherwise comprised it should be changed and all active API keys should be retired and reissued. Default value is 'changeme'. * Type: string ### CIVIFORM\_API\_KEYS\_BAN\_GLOBAL\_SUBNET **Server setting** When true prevents the CiviForm admin from issuing API keys that allow callers from all IP addresses (i.e. a CIDR mask of /0). * Type: bool ### CIVIFORM\_API\_APPLICATIONS\_LIST\_MAX\_PAGE\_SIZE **Admin readable** An integer specifying the maximum number of entries returned in a page of results for the applications export API. * Type: int ## Durable Jobs Configuration options for the CiviForm Job Runner. ### DURABLE\_JOBS\_POLL\_INTERVAL\_SECONDS **Server setting** An integer specifying the polling interval in seconds for the durable job system. A smaller number here increases the polling frequency, which results in jobs running sooner when they are scheduled to be run immediately, at the cost of more pressure on the database. Default value is 5. * Type: int ### DURABLE\_JOBS\_JOB\_TIMEOUT\_MINUTES **Server setting** An integer specifying the timeout in minutes for durable jobs i.e. how long a single job is allowed to run before the system attempts to interrupt it. Default value is 30. * Type: int ### DURABLE\_JOBS\_THREAD\_POOL\_SIZE **Server setting** The number of server threads available for the durable job runner. More than a single thread will the server execute multiple jobs in parallel. Default value is 1. * Type: int ### DURABLE\_JOBS\_MAP\_REFRESH **Server setting** A boolean specifying whether or not to refresh map data for the CiviForm instance. * Type: bool ## Session Management Configuration options for session management ### MAXIMUM\_SESSION\_DURATION\_MINUTES **Admin readable** The amount of time, in minutes, that a session lasts. The default is 600 minutes, or 10 hours. Note that there isn't yet messaging on the frontend to notify a user when their session is expired. * Type: int ### SESSION\_INACTIVITY\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the session inactivity timeout a user receives a warning that their session will expire. Default is 5. * Type: int ### SESSION\_DURATION\_WARNING\_THRESHOLD\_MINUTES **Admin readable** How many minutes before the maximum session duration timeout a user receives a warning that their session will expire. Default is 10. * Type: int ### SESSION\_INACTIVITY\_TIMEOUT\_MINUTES **Admin readable** The number of minutes of inactivity before a session times out. Default is 30. * Type: int ## Feature Flags Configuration options to enable or disable optional features. ### ALLOW\_CIVIFORM\_ADMIN\_ACCESS\_PROGRAMS **Admin writeable** If enabled, CiviForm Admins are able to see all applications for all programs. Is disabled by default. * Type: bool ### STAGING\_ADD\_NOINDEX\_META\_TAG **Server setting** If this is a staging deployment and this variable is set to true, a [robots noindex](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) metadata tag is added to the CiviForm pages. This causes the staging site to not be listed on search engines. * Type: bool ### STAGING\_DISABLE\_DEMO\_MODE\_LOGINS **Admin writeable** If this is a staging or demo deployment and this variable is set to true, the 'DEMO MODE. LOGIN AS:' buttons are not shown on the login page. Warning: if you turn on this flag, you will need to log in through the admin authenticator to get back to this settings page * Type: bool ### VERSION\_CACHE\_ENABLED **Server setting** Enables caching for versions and their associated data. * Type: bool ### PROGRAM\_CACHE\_ENABLED **Server setting** Enables caching for programs and their associated data. * Type: bool ### QUESTION\_CACHE\_ENABLED **Server setting** Enables caching for questions and their associated data. * Type: bool ### ADMIN\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to admin identity provider. * Type: bool ### APPLICANT\_OIDC\_ENHANCED\_LOGOUT\_ENABLED **Admin readable** Enables populating more fields in OIDC logout requests to applicant identity provider. * Type: bool ### SUGGEST\_PROGRAMS\_ON\_APPLICATION\_CONFIRMATION\_PAGE **Admin writeable** Upsell: Add programs cards to the confirmation screen that an applicant sees after finishing an application. * Type: bool ### SHOW\_NOT\_PRODUCTION\_BANNER\_ENABLED **Admin writeable** Enabling this will add a banner to the site to tell applicants this is not Production and that they shouldn't submit real applications. Configure the CIVIC\_ENTITY\_PRODUCTION\_URL setting to also include a link to your production site. * Type: bool ### CUSTOMIZED\_ELIGIBILITY\_MESSAGE\_ENABLED **Admin writeable** Enables civiform admins to set up a customized eligibility message per screen. * Type: bool ### CUSTOM\_THEME\_COLORS\_ENABLED **Admin writeable** Enable using custom theme colors in the applicant UI. * Type: bool ### NAME\_SUFFIX\_DROPDOWN\_ENABLED **Admin writeable** Enables suffix dropdown field in name question. * Type: bool ### REMOVE\_DOWNLOAD\_FOR\_PROGRAM\_ADMINS\_ENABLED **Admin writeable** Remove the CSV/JSON/PDF download capability for Program Admins. * Type: bool ### YES\_NO\_QUESTION\_ENABLED **Admin readable** Enables being able to add a new yes/no question. * Type: bool ### EXTERNAL\_PROGRAM\_CARDS\_ENABLED **Admin readable** Enable showing external program cards. * Type: bool ### LOGIN\_DROPDOWN\_ENABLED **Admin writeable** Enables a dropdown for login that has both applicant and admin login. * Type: bool ### IMMIGRATION\_STATUS\_INFO\_BANNER\_ENABLED **Admin writeable** Enable showing an immigration status informational banner to applicants. * Type: bool ### SESSION\_TIMEOUT\_ENABLED **Admin writeable** Enable session timeout based on inactivity and maximum duration. * Type: bool ## Experimental These are **NOT READY FOR PRODUCTION USE**. Use these configuration options to enable or disable in-development features. ### PROGRAM\_SLUG\_URLS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Use program slugs instead of program IDs in URLs. * Type: bool ### TRANSLATION\_MANAGEMENT\_IMPROVEMENT\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables translation management improvement phase one * Type: bool ### API\_BRIDGE\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables changes to support API Bridge * Type: bool ### EXPANDED\_FORM\_LOGIC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables new visibility/eligibility condition editing UI and expanded logic capabilities for admin. * Type: bool ### ENUMERATOR\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which make it easier for admins to work with enumerators. * Type: bool ### FILE\_UPLOAD\_QUESTION\_IMPROVEMENTS\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enables improvements which allow for file upload questions on the same page as other question types. Uses a new file upload method that uploads applicant files through CiviForm servers. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable the admin UI migration in Thymeleaf. * Type: bool ### ADMIN\_UI\_MIGRATION\_SC\_EXTENDED\_ENABLED **Admin writeable** (NOT FOR PRODUCTION USE) Enable extended options in the admin UI migration in Thymeleaf. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable the new applicant-guest merging strategy. * Type: bool ### NEW\_APPLICANT\_GUEST\_MERGING\_STRATEGY\_DRY\_RUN\_ENABLED **Admin readable** (NOT FOR PRODUCTION USE) Enable dry run logging for the new applicant-guest merging strategy. * Type: bool --- [Next Page](/llms-full.txt/1)