> ## Documentation Index
> Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/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

<Tabs>
  <Tab title="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.
    </Note>

    ### Step 2: Create Kubernetes Secret

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

    ```yaml theme={null}
    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 (all base64 encoded):

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

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

    ### Step 3: Apply the Secret

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

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

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

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

    <Note>
      See the  [SambaStack.yaml Reference](/en/v1.2.0/sambastack/resources/sambastack-yaml) for a full example.
    </Note>

    ### Step 5: Apply the Configuration

    Update your Helm deployment:

    #### On-prem

    ```bash theme={null}
    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={null}
    helm upgrade sambastack \
      -f sambastack.yaml \
      --namespace sambastack \
      sambastack-<VERSION>.tgz
    ```

    <Info>
      `sambastack-<VERSION>.tgz` is your local copy of the Helm chart used for the upgrade. Contact SambaNova Support if you need further assistance.
    </Info>
  </Tab>

  <Tab title="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.
    </Note>

    ### Step 2: Create Kubernetes Secret

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

    ```yaml theme={null}
    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 (all base64 encoded):

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

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

    ### Step 3: Apply the Secret

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

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

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

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

    <Note>
      See the  [SambaStack.yaml Reference](/en/v1.2.0/sambastack/resources/sambastack-yaml) for a full example.
    </Note>

    ### Step 5: Apply the Configuration

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

    verify the secret:

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

    Example Output:

    ```text theme={null}
    oidc-auth                      Opaque           5          10s
    sambastack-oidc-auth           Opaque           5          7m53s
    ```
  </Tab>
</Tabs>

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

<Info>
  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.
</Info>