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

# Authentication

This page outlines the custom authentication configurations you can set up for your SambaStack cluster.

## Custom OIDC configuration

**SambaStack on-prem / Airgapped**

To integrate SambaStack with your organization's identity provider, configure custom OIDC authentication.

### Step 1: Gather required values

| **Source** | **Values** |
| :- | :- |
| Provided by your OIDC provider | `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ISSUER_URL`, `OIDC_REDIRECT_URI` |
| Random string to be created | `JWT_SECRET_KEY` |

These correspond to environment variables: `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ISSUER_URL`, `OIDC_REDIRECT_URI`, and `JWT_SECRET_KEY`.

> [!NOTE]
>
> Values will be base64-encoded during upload, even if provided as plain text.

### Step 2: Create Kubernetes Secret

To create the secret, make a file named `oidc-auth.yaml` with your OIDC provider details:

```yaml theme={}
apiVersion: v1
kind: Secret
metadata:
  name: oidc-auth
  namespace: sambastack
stringData:
  OIDC_CLIENT_ID: "<client-id>"
  OIDC_CLIENT_SECRET: "<client-secret>"
  OIDC_ISSUER_URL: "<oidc-issuer-url>"
  OIDC_REDIRECT_URI: "https://ui.<yourdomain>/web/auth/callback"
  JWT_SECRET_KEY: "<random-string>"
```

Replace the placeholders with your actual values (provided as plain text):

* `<client-id>`: Your OIDC client ID
* `<client-secret>`: Your OIDC client secret
* `<oidc-issuer-url>` : Unique URL from your Identity Provider
* `<yourdomain>`: Your organization's domain
* `<random-string>`: A securely generated random string for JWT signing

> [!NOTE]
>
> SambaNova provides the full registry URL and version number during handover. Contact your SambaNova representative for access credentials.

> [!NOTE]
>
> Ensure the `OIDC_REDIRECT_URI` matches your UI domain's callback endpoint: `https://ui.<yourdomain>/web/auth/callback`

### Step 3: Apply the Secret

```bash theme={}
kubectl apply -f oidc-auth.yaml
```

### Step 4: Update `sambastack.yaml`

Add the OIDC configuration to your `sambastack.yaml`:

```yaml theme={}
gateway:
  replicas: 3
  auth:
    enabled: true
    secretName: oidc-auth     # Must match the oidc-auth secret name
```

> [!NOTE]
>
> See the  [SambaStack.yaml Reference](/docs/en/v2.2.6/sambastack/resources/sambastack-yaml) for a full example.

### Step 5: Apply the Configuration

Update your Helm deployment:

#### On-prem

```bash theme={}
helm upgrade sambastack \
  -f sambastack.yaml \
  --namespace sambastack \
  oci://<REGISTRY_URL>/sambastack/sambastack
```

#### Airgapped

Use your local copy of the Helm chart instead of the OCI registry path:

```shellscript theme={}
helm upgrade sambastack \
  -f sambastack.yaml \
  --namespace sambastack \
  sambastack-<VERSION>.tgz
```

> [!NOTE]
>
> `sambastack-<VERSION>.tgz` is your local copy of the Helm chart used for the upgrade. Contact SambaNova Support if you need further assistance.

**SambaStack hosted**

To integrate SambaStack with your organization's identity provider, configure custom OIDC authentication.

### Step 1: Gather required values

| **Source** | **Values** |
| :- | :- |
| Provided by your OIDC provider | `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ISSUER_URL`, `OIDC_REDIRECT_URI` |
| Random string to be created | `JWT_SECRET_KEY` |

These correspond to environment variables: `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ISSUER_URL`, `OIDC_REDIRECT_URI`, and `JWT_SECRET_KEY`.

> [!NOTE]
>
> Values will be base64-encoded during upload, even if provided as plain text.

### Step 2: Create Kubernetes Secret

To create the secret, make a file named `oidc-auth.yaml` with your OIDC provider details:

```yaml theme={}
apiVersion: v1
kind: Secret
metadata:
  name: oidc-auth
  namespace: sambastack
stringData:
  OIDC_CLIENT_ID: "<client-id>"
  OIDC_CLIENT_SECRET: "<client-secret>"
  OIDC_ISSUER_URL: "<oidc-issuer-url>"
  OIDC_REDIRECT_URI: "https://ui.<yourdomain>/web/auth/callback"
  JWT_SECRET_KEY: "<random-string>"
```

Replace the placeholders with your actual values (provided as plain text):

* `<client-id>`: Your OIDC client ID
* `<client-secret>`: Your OIDC client secret
* `<oidc-issuer-url>` : Unique URL from your Identity Provider
* `<yourdomain>`: Your organization's domain
* `<random-string>`: A securely generated random string for JWT signing

> [!NOTE]
>
> SambaNova provides the full registry URL and version number during handover. Contact your SambaNova representative for access credentials.

> [!NOTE]
>
> Ensure the `OIDC_REDIRECT_URI` matches your UI domain's callback endpoint: `https://ui.<yourdomain>/web/auth/callback`

### Step 3: Apply the Secret

```bash theme={}
kubectl apply -f oidc-auth.yaml
```

### Step 4: Update `sambastack.yaml`

Add the OIDC configuration to your `sambastack.yaml`:

```yaml theme={}
gateway:
  replicas: 3
  auth:
    enabled: true
    secretName: oidc-auth     # Must match the oidc-auth secret name
```

> [!NOTE]
>
> See the  [SambaStack.yaml Reference](/docs/en/v2.2.6/sambastack/resources/sambastack-yaml) for a full example.

### Step 5: Apply the Configuration

```bash theme={}
kubectl apply -f sambastack.yaml
```

verify the secret:

```shellscript theme={}
kubectl get secret | grep oidc
```

Example Output:

```text theme={}
oidc-auth                      Opaque           5          10s
sambastack-oidc-auth           Opaque           5          7m53s
```

## Keycloak user management

If using Keycloak as your primary authentication tool, refer to the [Keycloak Server Administration Guide](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-creating-user_server_administration_guide) for details on configuring your authentication setup.

> [!NOTE]
>
> Keycloak also supports the following:
>
> 1. [**Login activity tracking**](https://www.keycloak.org/docs/latest/server_admin/#configuring-auditing-to-track-events): View, export, and filter user activity by event type (login, logout, register).
> 2. [**LDAP integration**](https://www.keycloak.org/docs/latest/server_admin/index.html#_ldap): Federate multiple LDAP/AD servers in a single Keycloak realm and map LDAP user attributes to the Keycloak common user model.