# Authentication

## Prerequisites

* Download the [installation resources](/seldon-enterprise-platform/production-environment/observability-alerting/observability.md#installing-kube-prometheus).
* Verify the [cluster requirements](/seldon-enterprise-platform/production-environment.md#cluster-requirements).
* Install [Seldon Enterprise Platform](/seldon-enterprise-platform/production-environment/seldon-enterprise-platform.md).

## App-Level Authentication

Seldon Enterprise Platform can be set up to use app-level authentication with an OIDC provider, for example using the auth code flow. This would be particularly useful when gateway-level authentication is not set up for the Kubernetes cluster.

This feature can be activated by configuring the `install-values.yaml` file of the Seldon Enterprise Platform . This is done by setting the boolean variable `enableAppAuth` to `true` and further providing the OIDC configuration options as env variables to connect to OIDC providers such as Keycloak or Dex.

You can use any [Managed OIDC provider](#managed-keycloak-reference-configuration) to secure Seldon Enterprise Platform application.

```yaml
# boolean to enable app-level auth (defaults to "false")
enableAppAuth: true
```

### Add environment variables

1. Add the OIDC configuration to the env section in `install-values.yaml`file:

```yaml
env:
  OIDC_PROVIDER: ...     # oidc providerURL, e.g. 'https://$oidc_redirect_url/auth/realms/deploy-realm'
  CLIENT_ID: ...         # oidc client ID, e.g. 'deploy-server'
  CLIENT_SECRET: ...     # oidc client secret, e.g. 'deploy-secret'
  REDIRECT_URL: ...      # `$ISTIO_INGRESS/seldon-deploy/auth/callback`
  OIDC_SCOPES: ...       # oidc scopes (defaults to "profile email groups")
  USERID_CLAIM_KEY: ...  # claim to be used as userid (defaults to "preferred_username")
  USERNAME_CLAIM_KEY: ...  # claim to be used as username (defaults to "name")
  EMAIL_CLAIM_KEY: ...  # claim to be used as email (defaults to "email")
  GROUPS_CLAIM_KEY: ...  # claim to be used as groups (defaults to "groups")
  SA_ID_CLAIM_KEY: ...  # claim to be used as userid for service accounts (defaults to "preferred_username")
```

2. Change to the directory that contains the `install-values.yaml` file and then upgrade Seldon Enterprise Platform in the namespace `seldon-system`.

```
helm upgrade seldon-enterprise seldon-charts/seldon-deploy --namespace seldon-system -f install-values.yaml --version 2.4.0 --install
```

### Expected Claims

As Seldon Enterprise Platform integrates with OIDC providers, it expects to receive an **ID token** for authentication. This differs from an OAuth 2.0 access token by making certain claims non-optional and defining additional, standard claims for identity information.

Seldon Enterprise Platform expects the following claims in an ID token:

* `name` -- the name of the user determined by environment variable `USERNAME_CLAIM_KEY`
* `email` -- the user's email determined by environment variable `EMAIL_CLAIM_KEY`
* `groups` -- a list of groups to which the user belongs determined by environment variable `GROUPS_CLAIM_KEY`
* A unique user identity token. This is determined by environment variable `USERID_CLAIM_KEY`. This can be used for both human users and service accounts. If it is not possible to share claim keys for both, it is possible to use the environment variable `SA_ID_CLAIM_KEY` for service accounts.

{% hint style="info" %}
**Note**: the `USERID_CLAIM_KEY` is always used if present. `SA_ID_CLAIM_KEY` is used only if `USERID_CLAIM_KEY` does not exist in the token.
{% endhint %}

Whilst these claims are not mandatory, it is **highly recommended** to provide all of them as they are used for authorization and audit purposes. See helm chart for default values.

* The identity and `groups` claims are required for[ authorizing access](/seldon-enterprise-platform/production-environment/authorization.md).
* The `name` and `email` claims are used with GitOps to track which user performed an action, for example, and for other informational purposes.

### Groups/LDAP Configuration

Some customers choose to get groups from LDAP. See the [LDAP section](/seldon-enterprise-platform/operations/ldap-integration.md) on that.

### Identity Brokering

Sometimes there's an existing identity server that doesn't support OIDC and instead supports SAML.

Seldon does not support SAML directly but [Keycloak can be used to broker to a SAML server](https://medium.com/keycloak/keycloak-as-an-identity-broker-an-identity-provider-af1b150ea94).

### Managed Keycloak reference configuration

{% hint style="info" %}
**Important**: The reference configuration is for demonstration purposes only. It's recommended to consult with your operations and security teams to determine the best practices for installing and integrating an OIDC provider within your organization.
{% endhint %}

**Prerequistes**

Obtain the IP address of the Seldon Enterprise Platform instance running with Istio:

```
ISTIO_INGRESS=$(kubectl get svc -n istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
ISTIO_INGRESS+=$(kubectl get svc -n istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

echo "Seldon Enterprise Platform: http://$ISTIO_INGRESS/seldon-deploy/"
```

[Skycloak](https://skycloak.io) is a popular managed Keycloak OIDC provider.

Detailed instructions to integrate Keycloak can be found in the [official guides](https://www.keycloak.org/getting-started/getting-started-kube#_log_in_to_the_admin_console).

1. Login to the Admin Console of the deployment that you created using [Skycloak](https://skycloak.io).
2. [Create a realm](https://www.keycloak.org/getting-started/getting-started-kube#_create_a_realm) named `seldon`.
3. [Create a user](https://www.keycloak.org/getting-started/getting-started-kube#_create_a_user).
4. [Create a client](https://www.keycloak.org/getting-started/getting-started-kube#_secure_the_first_application) named `sep` with **Valid redirect URIs** set as `http://$ISTIO_INGRESS/seldon-deploy/auth/callback`
5. Obtain the **Client Secret** for the client that you created from the **Credentials** tab for the client `sep`.
6. Update the `install-values.yaml` file with these values.

```yaml
  # boolean to enable app-level auth (defaults to "false")
enableAppAuth: true

env:
  CLIENT_ID: "sep"
  CLIENT_SECRET: "<sep-client-secret>"
  OIDC_PROVIDER: "{sky_cloak_deplyment_uri}/realms/seldon/protocol/openid-connect/auth"    # example: https://fc4dba59-f6ea-4f05-9fd2-37ff194947ba.app.skycloak.io/realms/seldon/protocol/openid-connect/auth
  REDIRECT_URL: "http://$ISTIO_INGRESS/seldon-deploy/auth/callback"
```

7. Change to the directory that contains the `install-values.yaml` file and then upgrade the Seldon Enterprise Platform installation in the namespace `seldon-system`.

   ```
   helm upgrade seldon-enterprise seldon-charts/seldon-deploy --namespace seldon-system -f install-values.yaml --version 2.4.0 --install

   ```
8. To verify that Seldon Enterprise Platform application is secured by Keycloak OIDC provider, get the `Authorization URL` for the user that you created in the Keycloak console..

```bash
export KEYCLOAK_URL="{sky_cloak_deplyment_uri}" # example: https://fc4dba59-f6ea-4f05-9fd2-37ff194947ba.app.skycloak.io
export REALM="seldon"
export CLIENT_ID="sep"
export REDIRECT_URI="http://$ISTIO_INGRESS/seldon-deploy/auth/callback"
export AUTH_URL="${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/auth?client_id=${CLIENT_ID}&response_type=code&scope=openid&redirect_uri=${REDIRECT_URI}"
echo "Authorization URL: ${AUTH_URL}"
```

9. Open your browser and navigate to the `Authorization URL` and login with the credentials of the `user` that you [created](https://www.keycloak.org/getting-started/getting-started-kube#_create_a_user) in the Keycloak console.

You should be redirected to the Seldon Enterprise Platform.

### Troubleshooting

There's some details on debugging the token content in the [LDAP section](/seldon-enterprise-platform/operations/ldap-integration.md).

Often the issue is the auth configuration rather than Seldon specifically. In those cases it can be useful to connect a different application that dumps more details.

We provide an [example app](https://github.com/SeldonIO/oauth2-test-tool) for debugging purposes. It can be run on the cluster alongside Seldon Enterprise Platform.

Or you can edit your Seldon Enterprise Platform installation and replace the Docker image with that one. To do this, first find the deployment for Seldon Enterprise Platform and find what image it is using:

```
kubectl get deployment -n seldon-system seldon-deploy -o jsonpath="{..image}"
```

Then make a note of that and save the note. Next edit the deployment with `kubectl edit deployment -n seldon-system seldon-deploy`. Change the image to `seldonio/oauth-test-tool:0.1`.

When you log into Seldon Enterprise Platform, you'll actually be directed to the test tool. The Pod logs for the tool provide additional details about the login process. Once debugging is complete and the issue is resolved, you can revert the image to its original state.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.seldon.ai/seldon-enterprise-platform/production-environment/auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.