> 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/passwordless-for-linux-ssh/installation.md).

# Installation

***

### Installing the PAM Package

**RHEL**

```shell
# Install prerequisites
sudo yum install -y tar libuuid vim-common libcurl

# Install 1Kosmos PAM
sudo ./blockId.<version>.<timestamp>.sh
```

**Ubuntu**

```shell
# Install prerequisites
sudo apt install uuid-runtime libcurl4

# Install 1Kosmos PAM
sudo ./blockId.<version>.<timestamp>.sh
```

***

### Configuring the License File

After installation, update the `license_config` file at `/opt/BlockId/data/license_config` with your tenant details. Only a root user can modify this file. Use a text editor such as `vi` to set the following parameters:

```
TENANT_DNS=yourtenant.1kosmos.net
COMMUNITY=yourcommunity
```

<figure><img src="/files/ehKkqL8NaEXuhjdP1wJj" alt=""><figcaption></figcaption></figure>

***

### Configuring PAM Files

{% hint style="info" %}
Keep an additional root shell open before making any changes to PAM or sshd configuration to avoid locking yourself out. Back up all files before modifying them, and verify PAM configuration works locally before testing over SSH.
{% endhint %}

#### RHEL — password-auth

Update `/etc/pam.d/password-auth` to ensure 1Kosmos 2FA is not bypassed:

* Do not have any `auth` rule with a control flag set to `sufficient` or `[...success=done...]` — these will bypass all subsequent PAM rules including 1Kosmos
* Replace any such rules with `[success=X default=ignore]`, where X is the number of `auth` rules below the current one in the file
* Ensure the last `auth` rule (`pam_deny.so`) has its control flag set to `requisite`

**Example:** If `auth sufficient pam_sss.so forward_pass` has three `auth` rules below it, update it to:

```
auth   [success=3 default=ignore]   pam_sss.so forward_pass
```

If the last rule appears as `auth required pam_deny.so`, update it to:

```
auth   requisite   pam_deny.so
```

**password-auth — before modification:**

<figure><img src="/files/afd2TAPnC9ViKwf4veZL" alt=""><figcaption></figcaption></figure>

**password-auth — after modification:**

<figure><img src="/files/1RMz0xcFqdX5XkFD6dH0" alt=""><figcaption></figcaption></figure>

#### RHEL — sshd

Update `/etc/pam.d/sshd`:

* Add the `pam_blockId.so` rule immediately after the primary authentication (typically `password-auth`) with control flag set to `requisite`
* Ensure no preceding PAM rules use `sufficient` or `success=done`
* If a `substack` entry exists before `pam_blockId.so`, change it to `include` and ensure it does not contain any `sufficient` or `success=done` rules

**sshd — before modification:**

<figure><img src="/files/XtWvACP53KnJxEJXlwQ9" alt=""><figcaption></figcaption></figure>

**sshd — after modification:**

<figure><img src="/files/dmthoMEDKIgmwaeikWRX" alt=""><figcaption></figcaption></figure>

#### Ubuntu — sshd

Update `/etc/pam.d/sshd`:

* Add the `pam_blockId.so` rule after the primary authentication (`common-auth`) with control flag set to `requisite`

**sshd — before modification:**

<figure><img src="/files/2x3urPpTTYfqcEUzTYNn" alt=""><figcaption></figcaption></figure>

**sshd — after modification:**

<figure><img src="/files/j4KQsh7YY93cZFAX5TZk" alt=""><figcaption></figcaption></figure>

***

### Configuring sshd\_config

Add the following flags to `/etc/ssh/sshd_config`:

| Flag                              | Value | Description                                               |
| --------------------------------- | ----- | --------------------------------------------------------- |
| `ChallengeResponseAuthentication` | yes   | Enables keyboard-interactive authentication               |
| `KbdInteractiveAuthentication`    | yes   | Deprecated alias for ChallengeResponseAuthentication      |
| `UsePAM`                          | yes   | Enables the PAM interface                                 |
| `MaxAuthTries`                    | 1     | Maximum authentication attempts per connection            |
| `PubkeyAuthentication`            | no    | Disables public key auth to prevent bypassing 1Kosmos MFA |

If `/etc/ssh/sshd_config.d/50-redhat.conf` exists, comment out the `ChallengeResponseAuthentication no` line.

**Note:** Restart sshd after any changes: `service sshd restart`

***

### Configuring SELinux (RHEL Only)

If SELinux is enabled on the host, additional permissions are required for the 1Kosmos PAM to function.

1. Verify SELinux status: `sestatus`
2. Set SELinux to permissive mode: `setenforce 0`
3. Install policycoreutils:

```shell
sudo yum -y install policycoreutils-python
# If not found:
sudo yum -y install policycoreutils-python-utils
```

4. Open a new terminal and SSH into the host — this generates the audit logs needed in the next step
5. Create a semodule from the audit logs:

```shell
sudo ausearch -c 'sshd' --raw | audit2allow -M BlockIDPAM
```

This creates two files: `BlockIDPAM.te` and `BlockIDPAM.pp`

6. Install the semodule:

```shell
sudo semodule -i BlockIDPAM.pp
```

7. Re-enable enforcing mode: `setenforce 1`

***

### Testing the Setup

SSH into the configured Linux host:

```shell
ssh <username>@<ip address>
```

After entering the correct password, the 1Kosmos 2FA login menu appears. The options displayed depend on the authentication methods configured for the Linux CP application in AdminX.


---

# 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/passwordless-for-linux-ssh/installation.md?ask=<question>&goal=<endgoal>
```

`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.