Drupal SSO with Okta

Drupal SSO with Okta: what the integration does and which method fits

Your editors sign in to Drupal with local passwords, and the identity team wants Okta to be the source of truth for who can sign in. The OpenID Connect module's built-in Okta client or the contributed samlauth SAML module can connect Drupal to Okta, and both can create a Drupal account on first sign-in. Okta stays the authentication authority, so passwords, multi-factor policy and session rules are enforced there. Drupal keeps its own user records, content ownership and roles, which means the work is planning, configuration, attribute and role mapping, and testing, carried out in the web and database infrastructure you control. The Drupal core and contributed modules involved are licensed under GPL-2.0-or-later and there is no paid Drupal edition, so the cost sits in implementation effort and ongoing maintenance of the modules, not in licensing.

Choose the OpenID Connect path when Okta is your only identity provider for this site and your team is comfortable with OAuth 2.0 and OIDC claims. The OpenID Connect module provides a pluggable client, and its stable 8.x-1.6 release supports Drupal ^9.5, ^10 and ^11. Choose samlauth when your Okta tenant already publishes SAML applications for other systems, when your security team wants SAML assertions and metadata exchange as the standard, or when you need attribute handling that is easier to audit in that format. The samlauth latest stable release, 8.x-3.14, supports Drupal 10.3 and later and Drupal 11, so confirm your exact Drupal version against both project pages before you commit. Record the decision, the Okta application type and the claims or attributes each method will carry in your design document.

Before you choose, confirm three things with your Okta administrators and your Drupal maintainers: which Okta groups should be allowed to sign in, whether editors need a different role than authors or only a subset of content types, and what should happen to existing local accounts after cutover. Local administrator accounts should remain available as a documented break-glass path that is tested. Plan for the module versions to be updated on the Drupal update routine, because provider changes and security releases on Drupal.org affect the login path directly. Ask any implementation partner to provide the written scope, test cases and rollback steps before work starts.

What you need in place before configuring Okta and Drupal

Most delays in Drupal SSO with Okta come from prerequisites that were never confirmed, not from the configuration itself. The cards below cover the Drupal and PHP versions, the module choice, Okta tenant access, the public hostname and callback planning, and the existing database and web server. Work through them before anyone creates an application in Okta.

Drupal and PHP versions

Confirm which Drupal release the site will run at go-live, because the PHP requirement follows the core version. Drupal 10 requires PHP 8.1 or later, Drupal 11 requires PHP 8.3 or later and Drupal 12 requires PHP 8.5 or later. No supported Drupal version runs on PHP 7. If the site is still on Drupal 7, SSO work should wait for the migration, since Drupal 7 security support ended on January 5, 2025 and Drupal 6 and 7 sites cannot be updated in place.

Choosing the contributed module

The OpenID Connect module has a built-in Okta client, and its stable 8.x-1.6 release supports Drupal ^9.5, ^10 and ^11. The SAML Authentication module (samlauth) is the alternative if your Okta tenant already issues SAML assertions to other services. Its latest stable release 8.x-3.14 supports Drupal 10.3 and later and Drupal 11. Pick one protocol before you build, and confirm the release notes for the exact Drupal version you run.

Okta tenant access and admin roles

Someone must hold an Okta role that can create and edit applications, assign users and groups, and view the authorization server settings. Ask your Okta administrator who will own the application record after go-live. Confirm with Okta which features your plan includes, such as group claims, SAML options and any provisioning features, because these depend on your contract and tenant configuration rather than on Drupal.

HTTPS on the public hostname

Identity providers return authorization codes and SAML responses only to HTTPS endpoints on a fixed public hostname. Decide the final hostname before you register anything in Okta, because changing it later means updating every redirect and metadata entry. Confirm that the certificate is valid, that it covers the hostname exactly, and that the site does not redirect callback paths to a different host.

Callback URLs and redirect planning

The OpenID Connect module builds a redirect URI from the site address, and Okta will reject sign-in if the registered value does not match it exactly. Plan separate values for local development, staging and production, and record each one in the Okta application. Also note the post-logout behavior you want, because sign-out and session handling need their own registered URLs.

Time sync and existing stack

Token and assertion validity windows depend on accurate clocks, so confirm that the Drupal web servers and the database hosts sync time with a trusted source. Then record the web server (Apache or Nginx) and the database (MariaDB, MySQL, PostgreSQL or SQLite) the site already runs, along with their versions. Drupal supports all of these, but the module setup, cron schedule and backup routine should match the stack you actually operate.

Choosing between the Okta client in OpenID Connect and SAML

The OpenID Connect module provides a pluggable client for the OpenID Connect protocol, which sits on top of OAuth 2.0. Drupal redirects the user to Okta, Okta authenticates the user and returns an ID token that Drupal validates before it signs the user in. The module includes a built-in Okta client, so the Okta-specific endpoints do not have to be assembled by hand. The stable 8.x-1.6 release supports Drupal ^9.5, ^10 and ^11.

Okta admin setup: create an OIDC web application in Okta, set the sign-in redirect URI that Drupal reports, and note the client ID, client secret and Okta domain.
Attribute delivery: user details arrive as claims in the ID token or from the userinfo endpoint, such as email, name and any groups claim the authorization server includes.
Account creation: the module can create Drupal accounts on first sign-in, so provisioning decisions (username, email matching, role assignment) must be settled before go-live.
Typical reasons to pick it: the estate is mostly OAuth or OIDC, the team already runs an OIDC client elsewhere, or the Drupal site is the only relying party.

Confirm the current Okta client options, supported claims and group handling on the OpenID Connect project page before you commit to this route.",

How to configure the Okta connection in order

This sequence takes a Drupal site from an Okta application record to a tested, rolled-out sign-in flow where new users are provisioned on first sign-in and editors receive the right role. Each step ends with a check you can run before moving on, and a local administrator path stays available throughout.

Create the Okta application and record credentials
In the Okta admin console, create an OpenID Connect web application for the Drupal site (or a SAML app if your standard requires SAML), and set the sign-in redirect URI for the staging hostname. Record the client ID and client secret in your secrets store, or export the SAML metadata XML and the signing certificate. Confirm the application is assigned only to the test group you plan to use. The step is done when the credentials are stored outside the Drupal codebase and you can read the application's issuer or metadata URL.
Install and enable the chosen module on staging
On a staging copy of the site, install the OpenID Connect module with its Okta client, or the SAML Authentication module (samlauth) if SAML is the chosen protocol, using Composer so the version is pinned in your repository. Enable the module and any submodule for your chosen client, and confirm the site is running a version the module supports. Check the module's project page for the current compatibility statement before you pin the version. The step is done when the module status page shows it enabled without errors in the recent log.
Register the redirect or assertion consumer URL
Take the callback path shown on the Drupal configuration page for your chosen module and register it exactly in Okta, matching scheme, host and trailing slash. For SAML, register the service provider entity ID and assertion consumer service URL from the samlauth metadata page in the Okta SAML settings. Run a sign-in attempt with an Okta test user. The step is done when Okta redirects back to Drupal without a redirect-URI mismatch or signature error in the watchdog log.
Configure the Okta client or SAML service provider
Enter the Okta issuer, client ID and secret for OpenID Connect, or import the Okta IdP metadata and certificate for SAML, in the module settings on staging only. Limit the scopes to what you need for identity, typically the openid, profile and email claims. Keep the local administrator login enabled. The step is done when the sign-in button appears on the login page and a test user can complete the Okta prompt and return to Drupal.
Set provisioning and first sign-in behavior
Decide whether Drupal creates an account automatically on first successful sign-in, and whether that account is active, blocked or pending approval. Set the behavior in the module, then decide how existing local accounts with the same email address are matched or refused, so no duplicate or takeover path exists. Test with a new Okta user who has no Drupal account. The step is done when one new account is created with the expected status and no second account appears for the same person on a repeat sign-in.
Map email, username and editor roles
Map the Okta email claim to the Drupal mail field and a stable identifier to the username, and confirm which claim is treated as the unique key. For editors, map an Okta group claim to the Drupal editor role, and keep administrator roles out of automatic mapping. Ask your identity team to confirm group names and which claim carries them, since these vary by Okta configuration. The step is done when a test account in the editor group receives the editor role and an account outside the group does not.
Test with a non-admin account and blocked user
Sign in with a standard Okta user who is not an administrator, and confirm the account gets the expected fields and roles and can reach only the pages it should. Then remove that user from the Okta group or deactivate the user, and confirm the next sign-in fails and the Drupal account is blocked or cannot be used. Record the results and any log entries for your security team. The step is done when both the access test and the blocked-user test pass on staging.
Roll out and keep a local administrator path
Repeat the verified configuration on production with the production Okta application and secrets, then sign in once with Okta and once with the local administrator account to confirm both work. Document where the local administrator credentials are kept, who can use them, and the procedure for recovering access if Okta is unavailable. Review the module's security advisories and update channel through the Drupal Security Team page so the integration is patched with the rest of the site. The step is done when production sign-in works through Okta and the documented local fallback has been tested.

Mapping Okta attributes and groups to Drupal accounts and editor roles

This table pairs each Okta claim or SAML attribute with the Drupal user field, role or lifecycle behavior it should drive. Read it as a draft for the access model: each row names who decides the value and what to confirm in the module version you select before build. The main takeaway is that the mapping is a policy decision agreed with the identity team first, and the Drupal configuration simply records it.

Okta source	Drupal target	Decision owner	Confirm in the chosen module version
Subject or NameID	External identifier linked to the Drupal account	Identity team	Which claim the OpenID Connect Okta client uses as the stable subject, and that it is stored per provider
Email claim	Drupal account email	Identity team with the editorial lead	Whether email updates on later sign-ins or only on first creation, and how collisions with existing accounts are handled
Name or display name claim	Display name field	Editorial lead	Which claims are mapped to user fields by default and how custom claims are added
Username policy	Drupal username	Platform owner	How usernames are generated on first sign-in and whether they can be overridden by an administrator
Okta group membership	Drupal roles such as editor or administrator	Identity team with content owners	Whether group claims are passed by the Okta client or require a SAML attribute, and how role removal is applied
Administrator role	Drupal administrator role	CISO or platform owner	That administrator assignment is restricted to a named, small group and is never granted by default on first sign-in
Account creation on first sign-in	Provisioned Drupal account	Platform owner	Whether accounts are created automatically, which default role applies and whether new accounts need approval
Deprovisioning and blocking	Blocked Drupal account and retained content	Identity team and content owner	Whether removing a user in Okta blocks the Drupal account at next sign-in, and how content ownership is reassigned

Why the Okta login fails and how to fix it

This table pairs each common Okta sign-in failure on Drupal with its likely cause and a check the team can run to confirm it. Work through the rows in order when a login breaks, since the first few usually sit at the redirect, hostname and claim layers. The main takeaway is that most failures trace back to a mismatch between Okta's app settings and what Drupal sends or expects.

Failure	Likely cause	Check to run
Redirect URI mismatch	The callback URL registered in the Okta app does not match the Drupal callback path exactly, including trailing slashes and language prefixes.	Compare the redirect URI in the Okta application settings with the one shown in the OpenID Connect client configuration, character by character.
Assertion consumer URL mismatch (SAML)	The ACS URL in the Okta SAML app points to a different path than the samlauth service provider endpoint.	Open the Drupal SAML service provider metadata and confirm the ACS location matches the Okta single sign-on URL.
Wrong hostname or HTTP instead of HTTPS	The site is reached through an internal hostname, a load balancer alias or plain HTTP, so generated callback URLs do not match what Okta allows.	Check the trusted proxy and base URL settings, then confirm the callback URL Drupal generates uses the public HTTPS hostname.
Missing email claim or attribute	Okta does not release the email scope or attribute, so Drupal cannot match or create the account.	Decode a test ID token or SAML response and confirm an email value is present under the expected claim or attribute name.
Group claims not sent	The groups claim is not configured on the Okta authorization server or the SAML attribute statement, so role mapping receives no input.	Sign in as a test user in the target group and confirm the groups value appears in the token or assertion.
Accounts created with the wrong roles	Role mapping rules are missing or ordered incorrectly, so first sign-in assigns default roles or the wrong editor role.	Create a test user in each Okta group, sign in once, and confirm the resulting Drupal roles match the mapping table.
Duplicate accounts from username collisions	An existing local account has the same username or email as an Okta user, and the module creates a second account instead of linking them.	Search the user list for duplicate emails and usernames before go-live, and confirm the account-linking setting matches your policy.
Clock skew on SAML assertions	The Drupal server or Okta clock drifts, so the assertion looks not yet valid or already expired.	Compare server time with a trusted time source on every web node and review the assertion timestamps in a failed response.
Expired or rotated client secrets or certificates	The Okta client secret or SAML signing certificate has expired or was rotated without updating Drupal.	Check the expiry dates in Okta and in the Drupal configuration, and set a reminder before each one lapses.
Module version incompatible with Drupal core	The installed OpenID Connect or samlauth release does not support the running Drupal core version, so code paths fail after an upgrade.	Compare the module's supported Drupal versions on its project page with the output of the Drupal version check before and after each core upgrade.
Local admin lockout	SSO is enforced for all accounts, including the only administrator, and the Okta configuration fails.	Keep a documented break-glass administrator with a local login, test it in staging, and confirm it works before turning on enforcement.

Security settings that matter for an Okta-backed Drupal login

An Okta-backed Drupal login is only as strong as the settings on both sides of the handshake. The cards below cover the Drupal-side secrets, the Okta-side assignment and MFA policy, the role mapping that decides who can edit or administer the site, the emergency access path, and the patch process for the modules that handle sign-in.

Keep the client secret out of the codebase

The OpenID Connect client secret (or the SAML service provider private key, if you use samlauth) should live in a secrets store or the hosting platform's secret mechanism, not in exported configuration or a Git repository. Check that configuration exports do not include the secret, that staging and production use different Okta applications, and that rotating the secret is a documented procedure. Ask your Okta administrator which secret the application uses and when it expires. Exported configuration is the most common leak path.

Restrict Okta application assignments

Assign the Drupal application in Okta only to the people and groups who should sign in to this site, rather than to every user in the org. Users outside the assignment should be refused at Okta before Drupal sees the request. Confirm with your Okta administrator which assignment and access rules are available on your Okta edition, and test with a user who is not assigned to confirm the refusal works.

Enforce MFA in the Okta policy

Multi-factor authentication should be enforced by the Okta sign-on policy that applies to the Drupal application, so that Drupal never receives a session that skipped it. Drupal does not add its own check on top of Okta's result, so a weak policy is passed straight through. Ask your Okta administrator to confirm which factors and assurance levels the policy can require, and to test a sign-in with a second factor disabled to confirm it is blocked.

Limit who can become an editor or administrator

Role mapping decides who gets editorial or administrative rights in Drupal. Map only a narrow Okta group to the editor role, and never map a broad group such as all employees to administrator. Review the mapping whenever groups change, and remember that the role is refreshed at sign-in, so removing someone from the Okta group takes effect on their next login, not immediately. Confirm the exact claim your mapping reads with the module documentation before you go live.

Keep a break-glass local administrator

Keep one local Drupal administrator account with a strong password stored in a sealed, audited location, and do not use it for daily work. It is the way back in if Okta, the OIDC client configuration or the certificate used for SAML fails, or if the Okta tenant is unavailable. Test the procedure during go-live, and confirm that the account is excluded from automatic role changes and that its use is logged and reviewed.

Track advisories for sign-in modules

Subscribe your team to Drupal Security Team advisories for the OpenID Connect or samlauth modules and for Drupal core. Security releases are published on the third Wednesday of the month, so plan a standing window in that week to test and deploy patches, and have a faster path for advisories marked critical. Track the advisories against the versions in your build, since a patch on a module can also require a core update.

Questions buyers ask before hiring help for Drupal SSO with Okta

What drives the cost and effort of Drupal SSO with Okta?

The main drivers are the integration method, the number of role mappings, the state of your existing SAML or OIDC setup, the testing scope and the number of environments. Choosing the built-in Okta client of the OpenID Connect module or SAML through the SAML Authentication module changes the configuration and testing work, and each role an editor needs adds mapping logic and test cases. Ask any partner for a quote that lists each environment (development, staging, production), the test users and cases covered, and whether role mapping is in scope. Setup cost is one-time, while module updates, certificate renewals and access reviews recur after launch.

Can an in-house team set up Drupal SSO with Okta alone?

Yes, a team can do it alone if it has working knowledge of both Drupal administration and Okta administration. The Drupal side needs someone comfortable with contributed modules, configuration management and PHP-level debugging when a claim or attribute is missing. The Okta side needs someone who can create the application integration, assign groups, control which attributes are released and read sign-on logs. Teams without that combination usually benefit from a partner for the design and first build, then take over operations. Confirm skill coverage before committing, especially for the first production cutover.

How long does it take to scope and deliver Drupal SSO with Okta?

Duration depends on the written scope, not on a fixed template. The schedule is driven by how many environments need the integration, how many roles must map to Okta groups, whether your identity model is already settled, and how much testing your security and compliance teams require. Most engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts. Ask for a timeline tied to named milestones such as design sign-off, staging validation and production cutover, and confirm which of those depend on your own Okta or change-approval cycles.

What must our team provide before the integration work starts?

Plan to provide the following before work begins:

Okta administrator access, or a named admin who can create and test the application integration
A written role model that maps Drupal roles, especially editor roles, to Okta groups
Test users in Okta covering each role, plus a sign-off owner for test results
Final hostnames for each Drupal environment and the redirect URIs they will use
TLS certificates for those hostnames, and for SAML, the signing certificate and metadata exchange process

Missing hostnames or certificates are the most common reasons a schedule slips, so confirm them during scoping.

What recurs after Drupal SSO with Okta goes live?

Several items recur after launch. Contributed modules such as the OpenID Connect module or SAML Authentication module need updates as they receive fixes, and Drupal core needs regular bugfix and security releases. Security releases follow a published schedule, so someone must watch advisories and test updates against the SSO login path before deploying. Client secrets, private keys and certificates need rotation before they expire. Periodic access reviews should confirm that editor roles still match Okta group membership and that leavers lose access. Budget for these as ongoing operations, whether handled internally or under a support retainer.

Does DeployOpen issue an audit report for our Okta and Drupal integration?

No. DeployOpen does not issue audit reports, attestations or certifications. DeployOpen can prepare systems, configuration records, access-review procedures and other evidence that an assessment will examine. An independent auditor or certification body then performs the assessment and issues any report. If your organization needs SSO evidence for a compliance program, agree in the written scope which artifacts will be delivered, and confirm with your auditor which evidence they expect before implementation starts.

Should we choose the Okta client in the OpenID Connect module or SAML?

Choose based on what your Okta tenant and downstream applications already use. The OpenID Connect module includes a built-in Okta client, which suits teams standardizing on OIDC across applications. The SAML Authentication module, known as samlauth, lets Drupal act as a SAML service provider and suits organizations that already run SAML for most applications. The SAML module's latest stable release supports Drupal 10.3 and later and Drupal 11, so confirm your Drupal version before deciding. Ask a partner to compare both options against your attribute release needs and role mapping design.

How DeployOpen scopes and delivers Drupal SSO with Okta

DeployOpen plans, builds, documents and supports Drupal SSO with Okta inside your own infrastructure, from the Okta tenant settings to the Drupal site configuration. Engagements are fixed-scope, so the sign-in path, account provisioning and editor role mapping are agreed in writing before any build work starts.

How we scope

Confirm which Okta features, app types and sign-in paths your tenant already uses before choosing the client.
Agree in writing whether the built-in Okta client or SAML is the target, with the reasons recorded.
Define how editor roles map from Okta groups, and who approves changes to that mapping.

How we build

Configure the Okta application, redirect URIs and claims in a non-production Drupal environment first.
Set up first sign-in account creation, email matching and profile field sync, then test each path.
Test sign-in, sign-out, group changes and deprovisioned users against the agreed role model.

How we hand over

Document every Okta setting, Drupal configuration key and role mapping rule used in the build.
Walk your identity and Drupal teams through the runbook for rotating client secrets and changing groups.
Deliver a test record that shows which accounts and roles each scenario produced.

How we support

Review the OpenID Connect module and Drupal version compatibility before each planned upgrade.
Retest sign-in and role mapping after Drupal core or module releases that affect authentication.
Ongoing support and upgrades are available as a retainer, scoped in writing separately from the build.

Drupal SSO with Okta