Back to BlogOkta SSO Integration: Configure OIDC or SAML, Then Test Both Sides

Okta SSO Integration: Configure OIDC or SAML, Then Test Both Sides

NTNetverge TeamNetverge editorial teamPublished
okta saml integrationOkta authentication setupSSO integration guideokta sso integrationOkta for enterprise applications

Register your app as an integration in the Okta Admin Console, then choose OIDC with Authorization Code and PKCE for modern web, mobile, and single-page apps, or SAML 2.0 for legacy service providers that require it. Capture the Client ID and Secret (OIDC) or the SAML metadata and certificate, configure your redirect or ACS URLs precisely, and validate the result from both the service provider and Okta sides before rollout.

TL;DR:

  • Before opening Okta’s Admin Console, secure app creation rights and gather exact callback or ACS URLs, required attributes, provisioning needs, and certificates.
  • For OIDC, request openid profile email, add offline_access only for refresh tokens, enforce PKCE in public clients, and never place client secrets in frontend code.
  • For SAML, enter the service provider’s ACS endpoint and entity ID, preview the assertion, exchange metadata, and track the signing certificate’s expiry.
  • Test app and Okta login paths and just in time provisioning with existing and new accounts, then verify each token or assertion’s claims.
  • When authentication fails, compare issuer domains and registered callback or ACS strings character for character, then check certificate validity and mapped claims.

Table of Contents

What you need before you open the Admin Console

A smooth setup depends on having the right information ready, not on the console itself. Before creating the integration, confirm you have administrative access with permission to create app integrations in Okta, plus the technical details your application already expects.

  • Admin Console access with rights to create and configure app integrations
  • Redirect or callback URIs for OIDC apps, or the Assertion Consumer Service (ACS) URL and SP Entity ID for SAML apps
  • A clear list of the user attributes or claims your app needs, and whether just-in-time (JIT) provisioning or inbound federation applies
  • Any SAML signing certificate or metadata file required for exchange with the service provider

Gathering these up front avoids the back-and-forth that usually stalls integration projects early in the project.

How to choose between OIDC and SAML (and when PKCE matters)

Most new integrations should use OIDC with the Authorization Code flow, since Okta's own guidance recommends it over the implicit flow for both web and single-page applications. SAML 2.0 remains the right call when the service provider only accepts SAML assertions, which is common with older enterprise platforms.

  • OIDC with Authorization Code and PKCE: the default for web apps, SPAs, and mobile clients
  • SAML 2.0: for legacy enterprise service providers with no OIDC support
  • WS-Federation: relevant only for specific legacy platforms that request it through Okta's template app

The protocols differ in how they return identity data: OIDC issues signed JSON Web Tokens from a token endpoint, while SAML returns an XML assertion posted directly to the ACS URL. That distinction shapes how you debug each one later.

Pro Tip: Default to OIDC with PKCE unless a specific vendor requirement forces SAML. It is easier to debug with standard JWT tools and avoids exposing client secrets in public clients.

Create and configure an OIDC app in Okta

Setting up an OIDC integration follows a consistent sequence inside the Admin Console, whether the target is a server-rendered web app or a single-page application.

  1. Go to Applications, select Create App Integration, choose OIDC, then pick Web Application or Single-Page Application depending on your architecture.
  2. Enter the Sign-in redirect URIs and Sign-out redirect URIs exactly as your app expects them.
  3. Save the integration and record the generated Client ID; for web apps, also record the Client Secret.
  4. Request the openid profile email scopes, adding offline_access when your app needs refresh tokens.
  5. Implement the Authorization Code flow; for SPAs, enforce PKCE and never embed a client secret in frontend code.
  6. Use an Okta SDK or a maintained OAuth library to exchange the authorization code for tokens, then validate the issuer, audience, and signature on every token received.

Okta's implementation guide confirms this exact sequence: register the app, add redirect URIs, save the Client ID and Secret, then authenticate the token exchange at the /token endpoint using those credentials.

One configuration detail causes a disproportionate share of support tickets: a redirect URI that is off by a trailing slash or protocol mismatch between what's registered in Okta and what the app sends. Matching the string exactly, character for character, is a straightforward way to help avoid a failed callback.

Create and configure a SAML 2.0 app in Okta

SAML setup asks for a different set of fields, centered on the assertion exchange rather than token endpoints.

  1. In Applications, select Create App Integration and choose SAML 2.0.
  2. Fill in the Single sign-on URL (your app's ACS endpoint), the Audience URI (your SP Entity ID), and the Name ID format your app expects.
  3. Use Okta's preview option to generate and review the SAML assertion XML before going live.
  4. Download or copy Okta's Identity Provider metadata and hand it to the service provider for configuration.
  5. Confirm the SAML signing certificate format and expiration date, and set a reminder to rotate it ahead of expiry.

Okta's documentation on SAML app integrations confirms the Single sign-on URL and Audience URI as required fields, along with certificate management on the Sign On tab.

Pro Tip: When the service provider can't supply final metadata up front, create the Okta integration with placeholder values first, then update the Issuer and ACS fields once the SP sends its real metadata. This bootstrapping approach keeps both sides moving in parallel.

Mapping attributes and adding groups or custom claims

Most applications need more than a basic identity confirmation. They need group membership or custom fields to drive authorization logic inside the app itself.

  • Add a groups claim to your OIDC authorization server configuration, choosing whether it belongs in the ID token or should be fetched from the userinfo endpoint, as described in Okta's groups claim guide
  • For SAML, configure attribute statements in the app's settings and map them to the correct profile fields
  • Decode a sample token or assertion with a JWT or SAML decoder to confirm the fields your app expects are actually present before connecting it to production

Skipping this verification step is a frequent reason an integration "works" in testing but fails to authorize users correctly once live.

Validation checklist: testing SP-initiated, IdP-initiated, and JIT flows

A working login screen does not mean the integration is solid. Okta's federation validation guide recommends testing both directions of the flow along with provisioning behavior before considering the setup complete.

  1. Test the SP-initiated flow by visiting your app's sign-in URL directly and confirming it redirects to Okta and returns correctly to your callback route.
  2. Test the IdP-initiated flow by launching the app from the Okta end-user dashboard and confirming a valid session starts.
  3. Test JIT provisioning by signing in with a test user who does not yet exist in the app and confirming the account is created automatically, a step also outlined in Okta's custom SAML app guidance.
  4. Validate the issuer, audience, signature, and claims on every token or assertion, running these tests in a private or incognito browser window to avoid stale session interference.

Pro Tip: Run every test case with both a user who already exists in the app and a brand-new user, since provisioning bugs rarely show up in the first scenario.

Priority troubleshooting checklist for common failures

Most integration failures trace back to a handful of repeat offenders. Working through them in order can help resolve many support cases quickly.

  • Issuer or custom domain mismatch: compare the issuer value in the request against the issuer in the returned token; Okta's support documentation notes that a custom domain must match consistently across the authorization server and token claims or validation fails silently.
  • Redirect URI or ACS mismatch: confirm the registered value in Okta matches the app's configuration exactly, including protocol, trailing slashes, and port.
  • SAML signature or certificate errors: check the certificate format and expiration date, and confirm the correct metadata was exchanged with the service provider.
  • Missing claims or groups: inspect the actual token or assertion contents, adjust the claims mapping, and retest rather than assuming the configuration screen reflects reality.
  • Refresh token problems: review the grant types enabled on the client and the rotation settings, since a mismatch here silently blocks token renewal.

Each of these failure modes leaves a distinct fingerprint in logs, so matching the symptom to the right fix saves hours of guesswork.

Operational and security best practices for Okta SSO

Keeping an Okta integration secure over time takes a short list of consistent habits rather than a one-time setup effort.

  • Use Authorization Code with PKCE for every single-page or mobile client, and request offline_access only when the app genuinely needs refresh tokens
  • Enable refresh token rotation where supported, a protection Okta's refresh token guide notes reduces the risk of a stolen token being reused
  • Store client secrets and signing certificates in a secured vault and rotate certificates on a defined schedule
  • Limit the claims included in tokens and avoid passing unnecessary personal data through them
  • Rely on Okta SDKs and current OAuth libraries rather than hand-rolled token handling, since library maintainers track protocol updates faster than most internal teams can

Pro Tip: Readers who also manage hardware-backed authentication alongside Okta SSO can review YubiKey integration resources for FIDO2 and WebAuthn support as a second factor.

What breaks in practice and how to avoid surprises

What breaks in practice and how to avoid surprises — overview diagram

The integrations that go sideways after launch are rarely the ones with exotic requirements. They're the ones where nobody wrote down which redirect URIs, client IDs, or certificate expiry dates belong to which app, so a routine certificate rotation later turns into an afternoon of guessing.

Keep a short matrix of browsers and platforms you test against, always in private windows, and automate token and assertion inspection during staging rather than relying on a manual spot check before each release.

— Jim

FAQ

How do I set up SAML SSO in Okta?

Create a SAML 2.0 app integration in the Admin Console, enter the Single sign-on URL (ACS) and Audience URI (SP Entity ID) the service provider gives you, then preview and exchange the generated assertion metadata. Okta's SAML app integration guide walks through each required field and the signing certificate setup.

Can I verify a user in Okta without a phone-based factor?

Yes, Okta supports multiple authentication factors beyond phone-based ones, including hardware security keys that use FIDO2 or WebAuthn standards. Teams already using YubiKey hardware keys can register them as a verification method instead of relying on SMS or push notifications.

How do I integrate Okta with Active Directory?

Okta connects to Active Directory through an inbound federation or directory integration setup, where user attributes and group memberships sync from AD into Okta's profile and claims mapping. Attribute mapping follows the same statement configuration used for other SAML and OIDC integrations, so test the mapped fields with a sample login before rolling it out broadly.

Is Okta a single sign-on tool or a multi-factor authentication tool?

Okta functions as both: it provides single sign-on through OIDC and SAML protocols, and it also supports multi-factor authentication as a layered security control on top of that sign-in. Most deployments use the two together, with SSO handling the identity handoff and MFA adding a verification step during authentication.

Why does my Okta OIDC integration throw an issuer mismatch error?

This can mean the issuer used when requesting a token does not match the issuer present in the returned token, often because of a custom domain configuration. Checking that the authorization server settings and token claims both reference the same domain consistently resolves most of these cases.

Sources