> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/organization-and-security/bluebricks-self-hosted-runner/registration-and-authentication.md).

# Registration and Authentication

Bluebricks Self-Hosted Runner leverages our Kubernetes-native solution for passwordless, secure, and efficient task orchestration. This section outlines the registration and authentication flow that establishes the secure connection between your self-hosted cloud account and Bluebricks’ platform, and explains how Kubernetes JWT (JSON Web Tokens) are used.

### Overview

The registration and authentication process for Self-Hosted Runners ensures:

* **Secure and Passwordless Authentication:** Kubernetes JWT is utilized to validate service account identities without relying on static passwords.
* **Seamless Cluster Integration:** The Bluebricks API, in conjunction with Kubernetes’ built-in JWKS endpoint, securely registers and verifies clusters.
* **Dynamic Task Execution:** Once registered, tasks are securely assigned to the appropriate collection for further orchestration by the Bluebricks Deployments Controller (BDC).

> **Note:** A self-hosted cloud account (referred to as “Self-Hosted Runner”) is equivalent to a cloud account. It is directly associated with a collection and can be connected to multiple collections, allowing flexible management of Infrastructure as Code (IaC) tasks across diverse setups.

## Registration and authentication flow

### Registration process

The registration establishes the secure connection between your Kubernetes cluster and Bluebricks platform. Here's how it works:

{% @mermaid/diagram content="sequenceDiagram
participant Cluster as Your Kubernetes Cluster
participant API as Bluebricks
participant OIDC as Cluster OIDC Provider

```
Note over Cluster,OIDC: Secure Registration Process
Cluster->>API: Register cluster with OIDC address
API->>OIDC: Verify cluster identity
OIDC-->>API: Provide verification keys
API-->>Cluster: Registration confirmed
```

" fullWidth="false" %}

#### Steps to Register

1. Complete the Bluebricks Deployments Controller (BDC) installation
2. Run our registration script:

   ```bash
   /bin/bash -c "$(curl -fsSL https://brickscli.s3.eu-west-1.amazonaws.com/releases/latest/self-hosted-register.sh)"
   ```
3. The script will:
   * Verify your Kubernetes context
   * Guide you through a simple wizard to collect necessary details
   * Connect your cluster to Bluebricks platform

### How authentication works

After registration, your cluster communicates securely with Bluebricks using Kubernetes' built-in security features:

1. **Token-based Requests**: The BDC automatically sends authenticated requests using BDC cluster's service account tokens, those tokens are short lived, usually with 1 hour TTL (Depends on the cluster configuration)
2. **Automatic Verification**: Our platform verifies each request using your cluster's own security mechanisms
3. **Task Delivery**: Once verified, tasks are securely delivered to your collection

### Security assurance

Our authentication system is built on Kubernetes' enterprise-grade security standards:

* Uses native Kubernetes JWT tokens for all authentication
* Verifies every request against your cluster's own security endpoint
* Maintains complete isolation between different collections
* No passwords or external credentials to manage