> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault AppRole Requirements for Blink Runner

## Overview

Blink Runner supports authentication to [HashiCorp Vault](/docs/blink-platform/runners/secret-managers/hashicorp-vault) using the AppRole authentication method. AppRole enables Blink Runner to securely access secrets without requiring static root or administrative tokens.

With AppRole authentication, Blink Runner authenticates to Vault using two credentials:

* **role\_id** – Identifies the AppRole
* **secret\_id** – Authenticates Blink Runner as that AppRole

After successful authentication, Vault issues a short-lived client token. Blink Runner uses this token to perform secret operations such as reading, creating, updating, and deleting secrets.

Access to Vault resources is controlled entirely by the Vault policies attached to the AppRole.

This document describes the Vault-side configuration required to configure and validate AppRole authentication for Blink Runner.

***

## Required Vault AppRole Configuration

To enable Blink Runner authentication through AppRole, configure the following:

<Steps>
  <Step title="Enable AppRole Authentication">
    If AppRole is not already enabled, enable it in Vault:

    ```bash theme={"dark"}
    vault auth enable approle
    ```

    By default, Vault creates the AppRole authentication method at:

    ```text theme={"dark"}
    auth/approle
    ```

    The corresponding AppRole mount path is:

    ```text theme={"dark"}
    approle
    ```

    **Custom AppRole Mount Path**

    AppRole may also be mounted at a custom path.

    **Example:**

    ```bash theme={"dark"}
    vault auth enable -path=blink-runner approle
    ```

    This creates the authentication endpoint at:

    ```text theme={"dark"}
    auth/blink-runner
    ```

    The AppRole mount path becomes:

    ```text theme={"dark"}
    blink-runner
    ```

    <Note> The AppRole mount path controls only where authentication occurs. It does not determine where secrets are stored. </Note>
  </Step>

  <Step title="Create a Vault Policy">
    Blink Runner requires a Vault policy that grants access to the secret paths it will use.

    For example, if Blink Runner needs access under:

    ```text theme={"dark"}
    secret/blink/*
    ```

    and the secrets engine uses **KV v2**, the policy must allow access to both:

    * `data` paths
    * `metadata` paths

    **Example policy:**

    ```hcl theme={"dark"}
    path "secret/data/blink/*" {
      capabilities = ["create", "read", "update", "delete"]
    }

    path "secret/metadata/blink/*" {
      capabilities = ["read", "list", "delete"]
    }
    ```

    Write the policy to Vault:

    ```bash theme={"dark"}
    vault policy write blink-runner blink-runner-policy.hcl
    ```

    #### Policy Recommendations

    For production environments, Blink recommends applying least-privilege access.

    Grant access only to the secret paths required by Blink Runner and avoid overly broad permissions such as:

    ```text theme={"dark"}
    secret/data/*
    ```

    unless explicitly intended.
  </Step>

  <Step title="Create the AppRole">
    Create a dedicated AppRole for Blink Runner and attach the policy.

    Default AppRole mount:

    ```bash theme={"dark"}
    vault write auth/approle/role/blink-runner \
      token_policies=blink-runner \
      token_ttl=1h \
      token_max_ttl=4h
    ```

    **Custom AppRole Mount Path**

    If AppRole is mounted at a custom path, replace `auth/approle` with the custom mount path.

    Example:

    ```bash theme={"dark"}
    vault write auth/blink-runner/role/blink-runner \
      token_policies=blink-runner \
      token_ttl=1h \
      token_max_ttl=4h
    ```
  </Step>

  <Step title="Retrieve the Role ID">
    Retrieve the AppRole `role_id`:

    Default mount:

    ```bash theme={"dark"}
    vault read -field=role_id auth/approle/role/blink-runner/role-id
    ```

    Custom mount:

    ```bash theme={"dark"}
    vault read -field=role_id auth/blink-runner/role/blink-runner/role-id
    ```

    The `role_id` identifies the AppRole used by Blink Runner.
  </Step>

  <Step title="Generate a Secret ID">
    Generate a `secret_id` for the AppRole.

    Default mount:

    ```bash theme={"dark"}
    vault write -field=secret_id -f auth/approle/role/blink-runner/secret-id
    ```

    Custom mount:

    ```bash theme={"dark"}
    vault write -field=secret_id -f auth/blink-runner/role/blink-runner/secret-id
    ```

    <Note> Treat the `secret_id` as a sensitive credential and store it securely. </Note>
  </Step>

  <Step title="Validate AppRole Authentication">
    Validate the AppRole configuration by performing a login.

    Default mount:

    ```bash theme={"dark"}
    vault write auth/approle/login \
      role_id="<role_id>" \
      secret_id="<secret_id>"
    ```

    Custom mount:

    ```bash theme={"dark"}
    vault write auth/blink-runner/login \
      role_id="<role_id>" \
      secret_id="<secret_id>"
    ```

    A successful response returns a Vault client token.
  </Step>

  <Step title="Validate Secret Access">
    After authentication succeeds, verify that the returned token can access the expected secret paths.

    Example using KV v2:

    ```bash theme={"dark"}
    VAULT_TOKEN="<returned_client_token>" vault kv put secret/blink/test value=test

    VAULT_TOKEN="<returned_client_token>" vault kv get secret/blink/test

    VAULT_TOKEN="<returned_client_token>" vault kv delete secret/blink/test
    ```

    If these operations fail with:

    ```text theme={"dark"}
    permission denied
    ```

    the AppRole policy does not provide sufficient access to the configured secret path.
  </Step>

  <Step title="Navigate to Blink">
    To complete the integration, provide the following Vault details to Blink:

    * Vault address
    * AppRole mount path
    * `role_id`
    * `secret_id`
    * Secrets engine and secret path used by Blink Runner

    The Vault policy attached to the AppRole must allow Blink Runner to perform the required operations on the configured secrets path.
  </Step>
</Steps>

***

### Vault Authentication vs Secret Storage

AppRole authentication and secret storage are separate Vault components.

Authentication occurs under:

```text theme={"dark"}
auth/<approle_mount_path>/login
```

Secret access occurs under the configured secrets engine, for example:

```text theme={"dark"}
secret/data/blink/...
```

The AppRole mount path determines only where Blink Runner authenticates.

It does **not** control where secrets are stored.

***

### Operational Considerations

During startup, Blink Runner validates:

* Vault connectivity
* Authentication success
* Token validity

Vault enforces permissions when Blink Runner performs real secret operations. As a result, the AppRole policy must align with the actual secret paths Blink Runner is expected to use.

### Recommended Production Practices

Blink recommends the following operational practices:

* Use a dedicated AppRole for Blink Runner
* Apply least-privilege access policies
* Rotate `secret_id` values regularly
* Use short token TTLs where possible
* Avoid root or administrative tokens
* Store `role_id` and `secret_id` securely

***