> ## 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

> [tab] 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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/resources/sambastack-yaml.md) 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.

> [tab] 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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/resources/sambastack-yaml.md) 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.