> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/authentication/authentication-proxy/installation-and-configuration.md). # Installation & Configuration *** #### Creating an Auth Proxy configuration 1. In the AdminX interface, navigate to **Applications > Auth Proxy**. The **1K Auth Proxy for RADIUS / LDAP** page is displayed. 2. Click **+ Add New Configuration**. The **Create new Auth Proxy Configuration** page is displayed. 3. In the **Configuration Name** field, enter a name for the configuration. 4. In the **Supported Login Methods** section, select the appropriate authentication methods (**Login with Push**, **Login with Interactive Voice Response (IVR)**, and **Login with passcodes**). See [Authentication Methods ](/authentication/windows-workstation-mfa/authentication-methods.md)for details. 5. **(RADIUS only) Default Login Methods** — if you want the system to automatically trigger an authentication method when no credentials are provided over RADIUS, configure this section. When enabled, the system automatically attempts authentication using the selected method: * **Push** — sends a push notification to the user's biometrics-enabled device through the 1Kosmos Mobile Application; the user approves with their enrolled biometrics. * **Phone** — initiates a phone call to the user's registered number using IVR; the user follows the IVR instructions to approve. 6. **(RADIUS only) Client IP Attribute** — specify the RADIUS attribute used to capture the end-user client IP address. * This value is typically configured using attributes such as `Calling-Station-Id`. * When configured, the system captures the originating client IP instead of only the Auth Proxy server. * The captured client IP is included in authentication events such as `E_LOGIN_SUCCEEDED` and `E_LOGIN_FAILED`. 7. **(LDAP only) Skip MFA for Service Accounts** — optionally specify LDAP service accounts that can bypass MFA (see below). 8. Download the Auth Proxy server for your OS (Windows, Linux, or Mac). The download link contains a zip archive preconfigured with your community license key. 9. Click **Create** to save your configuration in AdminX. **Skipping MFA for service accounts (LDAP)** {% hint style="info" %} **Note:** Remember the config ID — it is required to run the Auth Proxy for RADIUS/LDAP. {% endhint %} Using the **Skip MFA for Service Accounts** section, community administrators can specify which LDAP service accounts bypass MFA. Specified accounts can be granted access with just a distinguishedName and password. 1. On the **Create new Auth Proxy Configuration** page, go to the **Skip MFA for Service Accounts** section. 2. Specify the conditions: | Condition | Operator | Value | | --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Groups | is one of / is not one of / contains / does not contain | 1. Click the blank text box; the **Add Groups** window appears. 2. Specify the group name for which MFA must be skipped. 3. Click **Save**. | 3. Click **Create**. #### Modifying an existing Auth Proxy configuration 1. Navigate to the configuration you want to edit and click the **pencil** icon in the **Actions** column. 2. Make your changes and click **Save**. You can also download another copy of the modified Auth Proxy server if desired. > **Note:** The wait time for these changes to take effect is 10 minutes. #### Deleting an existing Auth Proxy configuration 1. Navigate to the configuration you want to delete and click the **trash** icon in the **Actions** column. 2. In the **Delete Configuration** pop-up, click **Yes, delete**. {% hint style="info" %} **Note:** After removing the configuration, users cannot authenticate using the deleted Config ID. {% endhint %} #### Configuring hostname failover support Auth Proxy can connect to multiple domain controllers so authentication continues if the primary controller becomes unavailable. In the **Failover Support** section of the **Connection Information** tab under **Directory > Directory Integrations**, specify a list of domain controllers using host or IP address and port combinations. Click **Add another** to add controllers in sequence. Use the **Timeout in seconds** field to define the duration after which failover to the next host occurs if the primary host is unavailable. During authentication, Auth Proxy attempts the primary controller and automatically fails over to secondary controllers if the primary does not respond within the configured timeout. The **Retry Host after (in minutes)** field specifies the interval after which an inactive host is retried to determine whether availability has been restored. When a domain controller cannot be reached, Auth Proxy temporarily removes it from the pool of available hosts and skips it for authentication requests while inactive. After the cooldown period expires, the controller is automatically returned to service. If all configured controllers become unavailable at the same time, Auth Proxy resets their status and retries connections in the next authentication cycle, ensuring recovery without administrator intervention. **Host availability notifications** Enable the **Hostname Status Change Notifications** slider under the **Advanced Configuration** tab and specify the email address to be notified when host availability changes. Click **Add New** to notify multiple recipients. Each email includes the client ID of the Auth Proxy instance that reported the change. An **E\_HOSTNAME\_STATUSCHANGE** event is triggered whenever a configured host transitions between available and unavailable states. {% hint style="info" %} **Note:** If a host is reported as inactive and a notification email is sent, additional emails for the same host are suppressed for the next five minutes. {% endhint %} #### Configuring the community connection (license.json) After downloading the Auth Proxy based on your operating system, transfer the archive to your server and extract it to a folder of your choice. The folder includes the authProxy application, a `license.json` file, and several bash scripts. Use the `license.json` file to configure the details required to connect with 1Kosmos services. The structure is: ```json { "licenseKey": "xxxxxx-997b-xxxx-81f2-46a02be18b83", "tenantDNS": "acme.1kosmos.net", "communityId": "5f3d8d0cd866fa61019cf969" } ``` | Parameter | Description | Expected value | | -------------------- | ------------------------------------------------------------------------------- | ------------------ | | licenseKey | Contains the license key required to make the connection | `` | | tenantDNS | Contains the server to which the connection is established | `` | | communityID | Contains the name of the community | `` | | proxyURL (optional) | URL of the proxy | `` | | proxyUser (optional) | Username (RADIUS) or distinguishedName (LDAP) in case of an authenticated proxy | `` | **Example — tenant details only:** ```json { "licenseKey": "xxx-xxxx-xxxxx-xxxx-xxxx-xxxxxxx", "tenantDNS": "acme.1kosmos.net", "communityId": "5ffdsnjua61019dww986" } ``` **Example — tenant details and a proxy URL:** ```json { "licenseKey": "xxxx-xxxxxxxx-xxxxx-xxxxxx", "tenantDNS": "acme.1kosmos.net", "communityId": "5sxzzzxxxx9879", "proxyUrl": "http://proxy.example.com" } ``` **Example — tenant details, a proxy URL, and a proxy user:** ```json { "licenseKey": "xxxxxx-xxxxx-xxxx-xxxxxx", "tenantDNS": "acme.1kosmos.net", "communityId": "5fewwwjjz444544444sfxxxx", "proxyUrl": "http://proxy.example.com", "proxyUser": "proxy" } ``` #### Command line arguments Enter your Config ID from AdminX as your UUID. These strings must match for the RADIUS/LDAP server to work. Common parameters for both RADIUS and LDAP servers: * `-u ` (required) — set your `uuid`. Use your Config ID from AdminX. * `-p ` (optional) — set your proxy password. #### Managing logs and PID directories Logs for RADIUS and LDAP/LDAPS servers are written to a single log file. Each server instance has its own log file in the `port-/logs` directory, which is referenced when the server starts. If the directory does not exist when the server starts, it is created. **Sample log file:** ``` /work1/gosrc/github/go-authproxy/staging/acme-dev/port-1389/logs/default_20240718T140842.log ``` **Sample PID location:** ``` /work1/gosrc/github/go-authproxy/staging/acme-dev/port-1389/pid/pidFile.pid GoAuthProxy server started (pid=3327817) ``` Sample syntax to create directories for logs and PIDs: | Port | Example | | ------------- | -------------------------------------------------------------------------------------------------------------- | | 1812 (RADIUS) | `./startGoAuthProxy.bsh -p 1812 -u 20783f4d-fc7a-4133-b379-1224f1e3c92e -r` | | 1813 (RADIUS) | `./startGoAuthProxy.bsh -P 1813 -u 20783f4d-fc7a-4133-b379-1224f1e3c92e -r` | | 389 (LDAP) | `./startGoAuthProxy.bsh -u 20783f4d-fc7a-4133-b379-1224f1e3c92e -l ldap -b "ou=People,dc=example,dc=com"` | | 636 (LDAP) | `./startGoAuthProxy.bsh -u 20783f4d-fc7a-4133-b379-1224f1e3c92e -l ldaps -b "ou=People,dc=example,dc=com"` | | 1389 (LDAP) | `./startGoAuthProxy.bsh -u 20783f4d-fc7a-4133-b379-1224f1e3c92e -l ldap:1389 -b "ou=People,dc=example,dc=com"` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.1kosmos.com/authentication/authentication-proxy/installation-and-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.