Skip to main content

Configure Okta

Most organizations need both SSO and SCIM

The Willow OIN app provides SSO and SCIM provisioning in a single integration. If you want both (recommended for most organizations), follow the SCIM Provisioning with Okta guide instead: it covers the full SSO + SCIM setup in one place. This page covers SSO only.

Set up Okta as your identity provider using the Willow app in the Okta Integration Network (OIN).

Supported features​

SSO features​

  • SP-initiated SSO
  • IdP-initiated SSO

Before you start, note your Okta redirect URI: {gatewayUrl}/api/auth/callback/okta.

  • SaaS: https://acme-corp.withwillow.ai/api/auth/callback/okta
  • On-Premise: {CONNECT_URL}/api/auth/callback/okta

Add the Willow integration in Okta​

  1. Sign in to your Okta Admin Console at https://{your-org}-admin.okta.com/admin/apps/add-app
  2. Navigate to Applications and Resources → Applications, then select Browse App Catalog
  3. Search for Willow and select + Add Integration
  4. Fill in the application details:
    • Application label: "Willow" (recommended)
    • Willow Admin URL: app.withwillow.ai (SaaS) or your APP_URL (On-Premise)
    • Willow Connect URL: your Willow gateway URL, shown in the app (SaaS) or your CONNECT_URL (On-Premise)
  5. Select Done

Configure SSO in Okta​

  1. In the Willow app on Okta, go to the Sign On tab
  2. Select Edit
  3. Set Application username format to Email
  4. Select Save
  5. Copy the Client ID and Client Secret (shown on the Sign On tab for OIN OIDC apps)

For more details, see Okta's guide to adding app integrations from the catalog and assigning users to applications.

Finish in Willow​

  1. Go to Admin → Settings → Authentication Settings
  2. On the SSO Provider card, select Edit
  3. Select Provider: Okta
  4. Enter:
    • Client ID and Client Secret from the previous step
    • Issuer: your Okta org authorization server URL, which is your Okta domain with no path (e.g. https://dev-123456.okta.com). Use the domain without the -admin suffix (for example, acme-corp.okta.com, not acme-corp-admin.okta.com). Do not add a custom authorization server path such as /oauth2/default: the Willow app from the OIN catalog cannot use a custom authorization server, and sign-in fails with This client cannot use a custom authorization server. If you enable passthrough refresh token, the OIDC Token Endpoint must be this same server (https://dev-123456.okta.com/oauth2/v1/token), not /oauth2/default/v1/token.
  5. Select Save
SSO Provider dialog in Willow with Okta selected, showing the Client ID, Client Secret, Issuer, and Callback URL fields and the machine-user, passthrough, and enterprise-managed authentication options

Advanced options​

After saving, three optional settings are available beneath the credential fields:

Enable Client Credentials for Machine Users: lets machine users reach internal MCP servers that use proxy passthrough, by minting an OAuth token from this provider on their behalf (see Machine Users). When enabled, a Token Endpoint field appears, auto-discovered from your issuer's .well-known/openid-configuration.

Enable Client Credentials for Machine Users toggle with auto-discovered Token Endpoint field

Enable passthrough refresh token: forwards the user's SSO JWT to internal MCP servers automatically. When enabled, an OIDC Token Endpoint field appears, auto-discovered. See JWT Passthrough for the full setup.

Enable passthrough refresh token toggle with auto-discovered OIDC Token Endpoint field

Enable enterprise-managed authentication: lets Claude connect to Willow on behalf of your users through Okta, with no sign-in prompt (see Enterprise-Managed Authentication), and enables the auth exchange API. When enabled, a JWKS URI field appears, auto-discovered.

Enable enterprise-managed authentication toggle with auto-discovered JWKS URI field

Refresh tokens for passthrough​

With Enable passthrough refresh token on, Willow requests offline_access at sign-in, stores the user's Okta refresh token, and uses it to get a new token whenever the forwarded one expires (Okta ID tokens last 60 minutes). Users stay connected as long as that refresh token is valid.

  • Match the Okta refresh token lifetime to Willow's token expiration. A refresh token has a total lifetime and an idle timeout (how long it can go unused), both configured in Okta. Willow's Token Expiration controls how long the user's Willow session lasts, and the two are independent: if the Okta refresh token ends first, the user is still signed in to Willow but every call to a passthrough MCP server fails until they sign in again. Set both the Okta refresh token lifetime and idle timeout to at least Willow's token expiration (or the longest group override, if you use one). For example, with a 7-day Willow token expiration, an 8-hour Okta idle timeout breaks passthrough every morning, while a 7-day one does not.
  • Okta can end a refresh token early. Deactivating, suspending, or unassigning the user from the Willow app, clearing the user's sessions with token revocation, changing the Willow app's configuration, and refresh token reuse detection all revoke it before it expires.
  • Changes apply to new sign-ins only. Okta fixes a refresh token's lifetime when the user signs in, and a rotated token keeps its original expiry. Users signed in before a change keep their current token until they sign in again, so after raising the lifetime, ask users to sign in to Willow once.

When a user's refresh token is no longer valid, tool calls to passthrough MCP servers return a sign-in link. Signing in through it, or reconnecting the MCP client, sends the user through Okta and stores a new refresh token.

To find out why a refresh token ended, open the failed tool call in Monitor → Logs: the SSO step shows Okta's error and when the token was dropped. Then search the Okta System Log for that user and the Willow app around the same time. Reuse detection appears as app.oauth2.token.detect_reuse.

Assign users or groups​

In the Okta Admin Console, open the Willow app → Assignments tab → Assign → select users or groups.

After SSO is working, configure SCIM provisioning to automate user and group lifecycle management between Okta and Willow. When SCIM is active, Okta creates, updates, and deprovisions users and groups automatically. See SCIM Provisioning with Okta for step-by-step instructions.