Using an Auth Proxy with the SkyPilot API Server#

You can deploy the SkyPilot API server behind an web authentication proxy, such as OAuth2 Proxy, to use SSO providers such as Okta.

The SkyPilot implementation is quite flexible and will generally work behind most cookie-based browser auth proxies. See User flow and Optional: Bring your own auth proxy for details. To set up Okta, see Setting up OAuth2 Proxy with Okta.

SkyPilot with auth proxy

User flow#

While logging into an API server, SkyPilot will attempt to detect an auth proxy. If detected, the user must log in via a browser:

$ sky api login
Enter your SkyPilot API server endpoint: http://a.b.c.d
Authentication is needed. Please visit this URL to get a token:

http://a.b.c.d/token

Paste the token:

Opening http://a.b.c.d/token in the browser will force the user to authenticate as required by the auth proxy.

Okta auth page

After authentication, the user will be redirected to the SkyPilot token page:

SkyPilot token page

Copy and paste the token into the terminal to save the auth for the SkyPilot CLI.

...

http://a.b.c.d/token

Paste the token: eyJfb2F1dGgyX3Byb3h5IjogInVYcFRTTGZGSEVYeHVGWXB2NEc4dHNKTzVET253YkRVVEJ5SkVFM1cxYkg1V29TQVhSRk4tLXg1NFotT1hab0ZsV1BMUEJicTE2NXZmZmdWQ0FrVnQtMktlM0hpenczOWhLLTRMZ3...
Logged into SkyPilot API server at: http://a.b.c.d
└── Dashboard: http://a.b.c.d/dashboard

This will copy the relevant auth cookies from the browser into the CLI.

Setting up OAuth2 Proxy with Okta#

The SkyPilot API server helm chart can also deploy and configure OAuth2 Proxy to provide an out-of-the-box auth proxy setup.

Here’s how to set it up:

Create application in Okta#

From your Okta admin panel, navigate to Applications > Applications, then click the Create App Integration button.

  • For Sign-in method, choose OIDC - OpenID Connect

  • For Application type, chose Web Application

SkyPilot token page

Click Next.

Optionally, set a name for the application such as SkyPilot API Server. Then, set the following settings:

  • Set the Sign-in redirect URIs to <ENDPOINT>/oauth2/callback, where <ENDPOINT> is your API server endpoint. * e.g. http://a.b.c.d/oauth2/callback

  • Set Assignments > Controlled access to Allow everyone in your organization to access, unless you want to limit access to select groups.

Click Save. You will need the Client ID and a Client Secret in the next step.

Deploy in Helm#

Set up the environment variables for your API server deployment. NAMESPACE and RELEASE_NAME should be set to the currently installed namespace and release:

NAMESPACE=skypilot # TODO: change to your installed namespace
RELEASE_NAME=skypilot # TODO: change to your installed release name
VERSION=1.0.0-dev20250410 # TODO: change to the version you want to upgrade to
IMAGE_REPO=berkeleyskypilot/skypilot-nightly

Use helm upgrade to redeploy the API server helm chart with the skypilot-oauth2-proxy deployment. Replace <CLIENT ID> and <CLIENT SECRET> with the values from the Okta admin console above, and <OKTA URL> with your Okta login URL.

$ # --reuse-values is critical to keep the old values that aren't being updated here.
$ helm upgrade -n $NAMESPACE $RELEASE_NAME skypilot/skypilot-nightly --devel --reuse-values \
  --set ingress.oauth2-proxy.enabled=true \
  --set ingress.oauth2-proxy.oidc-issuer-url=https://<OKTA URL>.okta.com \
  --set ingress.oauth2-proxy.client-id=<CLIENT ID> \
  --set ingress.oauth2-proxy.client-secret=<CLIENT SECRET>

If your API server endpoint only has HTTP, not HTTPS, add --set ingress.oauth2-proxy.use-http=true.

To make sure it’s working, visit your endpoint URL in a browser. You should be redirected to Okta to sign in.

Now, you can use sky api login -e <ENDPOINT> to go though the login flow for the CLI.

Optional: Bring your own auth proxy#

Under the hood, SkyPilot uses cookies just like a browser to authenticate to an auth proxy. This means that most web authentication proxies should work with the SkyPilot API server. This can be convenient if you already have a standardized auth proxy setup for services you deploy.

To bring your own auth proxy, just configure it in front of the underlying SkyPilot API server, just like any other web application. Then, use the proxy’s address as the API server endpoint.

To log into the CLI, use sky api login as normal - it should automatically detect the auth proxy and redirect you into the special login flow.

During the login flow, the token provided by the web login will encode the cookies used for authentication. By pasting this into the CLI, the CLI will also be able to authenticate using the cookies.

SkyPilot auth proxy architecture

Note

If your auth proxy is not automatically detected, try using sky api login --cookies to force auth proxy mode.