Skip to main content
This guide covers the Okta-specific steps for authenticating dashboard users against Okta. See the dashboard authentication overview for how the built-in sidecar works and how the two auth modes compare.
If you already run your own oauth2-proxy sidecar against Okta from a pre-5.0 install, your app registration and Secret carry over unchanged. See Migrating from a hand-rolled oauth2-proxy sidecar.

​
Setup

​
1. Register an app in Okta

  1. In the Okta Admin Console, go to Applications -> Applications -> Create App Integration.
  2. Choose OIDC - OpenID Connect as the sign-in method and Web Application as the application type.
  3. Set a Sign-in redirect URI of https://thoras.yourcompany.com/oauth2/callback.
  4. Under Assignments, grant access to the group(s) that should be able to reach the dashboard (or “Everyone” for org-wide access).
  5. Once created, note the Client ID and Client secret from the app’s General tab, and your Okta domain (e.g. dev-133337.okta.com) from the top of the Admin Console.
Your issuer URL is https://<your-okta-domain>/oauth2/default if you’re using the default custom authorization server, https://<your-okta-domain>/oauth2/<auth-server-id> if you’ve configured a custom authorization server under Security -> API, or https://<your-okta-domain> if you’re using the org authorization server.
The default custom authorization server may not be available or usable. Custom authorization servers (including the one named default) are part of Okta’s API Access Management add-on. Production orgs that don’t have that add-on cannot use /oauth2/default at all, and newly provisioned Integrator Free Plan orgs ship without an Access Policy on it. Without a matching Access Policy, login fails with You are not allowed to access this app and a no_matching_policy error in the Okta system log. Fix it one of two ways:
  • Add an Access Policy to the default custom auth server under Security -> API -> Authorization Servers -> default -> Access Policies, then add a rule that applies to your app.
  • Use the org authorization server instead by dropping /oauth2/default from the issuer URL. Set the issuer to https://<your-okta-domain>. This works on every Okta org and needs no add-on. See Authorization servers (Okta docs).
See oauth2-proxy’s own Okta walkthrough (under the OpenID Connect provider, which is what Okta uses): OpenID Connect - Okta, and Okta’s writeup of the same integration: Add Auth to Any App with OAuth2 Proxy.

​
2. Create the Kubernetes secret

The sidecar needs three values, read from a Kubernetes Secret you manage rather than inlined in values.yaml. The chart never generates these: Generate the cookie secret with:
Create the secret (values below are base64-encoded automatically by kubectl when using --from-literal):

​
3. Switch the chart into OIDC mode

In values.yaml, set thorasDashboard.auth.mode: oidc and fill in the OIDC block:

​
Field notes

  • provider: oidc. oauth2-proxy has no Okta-specific provider; Okta is served by the generic OpenID Connect provider, which is what oauth2-proxy’s own Okta example uses. okta is not a valid value and the sidecar will fail to start.
  • issuerURL: points at your Okta authorization server. Use https://<your-okta-domain>/oauth2/default for the default custom authorization server, https://<your-okta-domain>/oauth2/<auth-server-id> for another custom one, or https://<your-okta-domain> for the org authorization server (see the Warning above).
  • redirectURL: must be the real external hostname of the dashboard, over HTTPS, and must exactly match the sign-in redirect URI registered on the Okta app.
  • emailDomains: restricts login to your org’s email domain(s). Use ["*"] to allow any authenticated user.
  • existingSecret.secretName: points at the Secret you created in step 2.

​
4. Deploy and verify

  1. helm upgrade the release with the updated values.yaml.
  2. Confirm the dashboard pod comes up healthy, and check the sidecar logs if something goes wrong:
  3. Visit the dashboard URL. You should be redirected to your identity provider’s login page, and land back on the dashboard after authenticating.
  4. If the redirect fails or loops, double-check that redirectURL exactly matches a redirect URI registered on your identity provider’s app, and that issuerURL is correct.

​
Exposing the sidecar externally

The chart’s built-in oauth2-proxy sidecar owns the dashboard’s containerPort, so the existing thorasDashboard Service already routes external traffic through the auth check. No service.targetPort override is needed. Expose the Service using whichever mechanism the chart already supports: Ingress
Gateway API
Adjust ingressClassName/parentRefs to match your cluster’s actual Ingress controller or Gateway, and terminate TLS there (or upstream at a cert-manager-issued Certificate bound to it). Once DNS for thoras.yourcompany.com resolves and a valid TLS cert is issued, visiting the dashboard URL should trigger the login flow described above.

​
Further reading