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 → 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. Select Provider: Okta
  3. 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.
  4. Select Save Changes
Okta SSO provider configured in Willow Authentication Settings

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 Auth Exchange (JWT to Connect credentials): enables JWT token verification using your IdP's JWKS endpoint. When enabled, a JWKS URI field appears, auto-discovered. Used to verify JWT tokens in the auth exchange API.

Enable Auth Exchange toggle with auto-discovered JWKS URI field

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.

On this page