Okta SSO for Zaun Partners

This guide walks an Okta admin through configuring single sign-on between their Okta tenant and the Zaun Partners portal at partners.zaun.ai.

How it works

Zaun Partners uses AWS Cognito as an OIDC broker that federates with your Okta tenant. End-user sign-in flow:

1. User visits https://partners.zaun.ai/sign-in
2. Clicks Continue with Okta
3. Cognito redirects to your Okta tenant for authentication
4. After authentication, Cognito issues a Zaun Partners session and the user lands in the portal

Zaun Partners does not support just-in-time user provisioning. Every user must be invited by a Zaun Partners admin before they can sign in, even after Okta SSO is wired up.

Prerequisites

• Okta admin access in your organization's Okta tenant
• An existing Zaun Partners account, or a contact at Zaun who can create one
• The list of users in your organization who need access

Setup overview

Step 1: Create the OIDC app in Okta

1. In your Okta admin console, go to Applications → Applications

2. Click Create App Integration

3. Sign-in method: OIDC – OpenID Connect

4. Application type: Web Application (this is important, Cognito requires a confidential client)

5. Click Next

6. Fill in the following:

   Field	Value
   App integration name	Zaun Partners
   Grant type	Authorization Code (only)
   Sign-in redirect URIs	https://zaun-partners.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
   Sign-out redirect URIs	https://zaun-partners.auth.us-east-1.amazoncognito.com/logout
   Initiate login URI (optional)	https://partners.zaun.ai/api/auth/sign-in?idp=Okta
   Controlled access	Choose how to assign access (recommended: assign by group)

7. Click Save

8. On the General tab of the new app, copy and securely store:

   • Client ID
   • Client secret (click "Show" to reveal)

9. Note your tenant's Issuer URL. For most Okta tenants this is https://<your-okta-domain>/oauth2/default. For example, if your tenant is https://acme.okta.com, the issuer is https://acme.okta.com/oauth2/default.

Step 2: Configure the authorization server access policy

The default authorization server needs a policy that allows the Zaun Partners client to request tokens. In most Okta tenants this is already configured, but verify:

1. Security → API → Authorization Servers → click default
2. Access Policies tab
3. There should be a policy named "Default Policy" (or similar) assigned to "All clients" (or explicitly including the Zaun Partners client)
4. Open the policy and confirm it has at least one rule with:
   • Grant types: Authorization Code (and Refresh Token if you want offline access)
   • Scopes: openid, email, profile
   • User: Any user

If no such policy exists, create one:

• Click Add Policy → name "Allow Zaun Partners" → assign to "All clients" (or specifically the Zaun Partners client) → Create
• Add a rule with the values listed above

Skipping this step results in a no_matching_policy error during sign-in.

Step 3: Send credentials to Zaun

Email [email protected] with the following information:

Subject: Okta SSO setup for <your company name>

Company name:     <your company>
Okta tenant URL:  https://<your-okta-domain>
Client ID:        <from Step 1.8>
Client secret:    <from Step 1.8>
Issuer URL:       <from Step 1.9>
Primary contact:  <name + email of your Okta admin>

Note: send the client secret over a secure channel. Use encrypted email or a password manager share link. Don't post it in chat or a ticket system.

Step 4: Zaun configures the federation

Zaun's team will register your Okta tenant as an OIDC identity provider in the Zaun Partners Cognito user pool. This typically takes one business day. You'll receive a confirmation email once it's live.

Step 5: Assign users in Okta

1. In Okta admin, go to Applications → Zaun Partners → Assignments
2. Click Assign → Assign to People or Assign to Groups
3. Add the users or groups who should have access

These same users must also be invited inside Zaun Partners (Step 6). Being assigned in Okta alone is not enough.

Step 6: Zaun invites users in the portal

Send the list of email addresses to your Zaun account contact. They'll create the corresponding user records in Zaun Partners. The email addresses you assign in Okta (Step 5) must match exactly. Zaun Partners maps users by email.

Step 7: Test sign-in

As one of the assigned users:

1. Go to https://partners.zaun.ai/sign-in
2. Click Continue with Okta
3. You'll be redirected to your Okta tenant
4. Authenticate (password, MFA, etc. per your Okta policies)
5. You'll be redirected back to Zaun Partners and land on the dashboard

Troubleshooting

When sign-in fails, the redirect URL usually ends with ?sso_error=<reason>. Include that reason when contacting support.

Security notes

• Zaun Partners session cookies are HTTP-only, secure, and SameSite=Lax. Sessions are signed independently from the Cognito/Okta tokens.
• Cognito verifies the Okta ID token signature against your tenant's JWKS on every sign-in.
• We rotate the client secret on request. Email [email protected] if you need to rotate.
• Disabling a user in Okta prevents future sign-ins. To revoke an existing session, also disable the user inside Zaun Partners.

Contact

• SSO and integration questions: [email protected]
• General product support: [email protected]