Single sign-on (SSO)

Set up Okta sign-in for the employee portal

Let your employees sign in to the Ploy employee portal with their Okta account. You create an OIDC app integration in your own Okta organization, then paste its details into Ploy. This is separate from Okta SAML single sign-on, which signs admins in to the Ploy dashboard, and from Ploy's Okta API integration, which imports your users.

Before you start

You need:

  • Admin access to your Okta organization.

  • Access to Settings → Portal config in Ploy.

  • Your employees already in Ploy. Ploy signs someone in only when the email Okta returns matches an employee in your organization.

Turn on Okta in Ploy

  1. In Ploy, go to Settings → Portal config.

  2. Under Login Options, click Okta to turn it on. The Okta sign-in panel appears below.

  3. Keep this page open. You copy the Sign-in redirect URI and the Initiate login URI from it into Okta.

Create the app integration in Okta

  1. In the Okta Admin Console, go to Applications → Applications and click Create App Integration.

  2. Choose OIDC - OpenID Connect as the sign-in method and Web Application as the application type, then click Next.

  3. Name it something recognisable, for example Ploy employee portal.

  4. Fill in the settings below, then click Save.

Okta field

Value

Grant type

Authorization Code. No other grant type is needed.

Sign-in redirect URIs

The Sign-in redirect URI from Ploy: https://api.employee-access.com/auth/okta/callback

Sign-out redirect URIs

Leave empty.

Controlled access

Who can use the portal: Limit access to selected groups, or Allow everyone in your organization to access.

Turn off PKCE and DPoP

Ploy authenticates with the client secret, so the app must not require PKCE or DPoP. On the app's General tab:

Setting

Value

Client authentication (under Client Credentials)

Client secret

Require PKCE as additional verification (under Client Credentials)

Unticked

Require Demonstrating Proof of Possession (DPoP) header in token requests (under General Settings)

Unticked

If PKCE or DPoP is ticked, Okta refuses the sign-in and the employee sees "Invalid authentication request. Please try again".

Show Ploy as a tile on the Okta dashboard (optional)

So employees can open the portal from their Okta End-User Dashboard, edit the LOGIN section of the app's General tab:

  1. Set Login initiated by to Either Okta or App.

  2. Tick Display application icon to users.

  3. Set Login flow to Redirect to app to initiate login (OIDC Compliant).

  4. Paste the Initiate login URI from Ploy into Initiate login URI. It looks like https://api.employee-access.com/auth/okta/request?subdomain=<your-portal-subdomain>.

  5. Click Save.

Assign the people who can sign in

On the app's Assignments tab, assign the people or groups who should use the employee portal. Okta only lets assigned people through.

Connect Ploy

Back in Ploy on Settings → Portal config, fill in the Okta sign-in panel, then click Save.

Ploy field

Where to find it in Okta

Okta domain

Your Okta address, for example acme.okta.com. The admin console address (acme-admin.okta.com) also works.

Client ID

The app's General tab, under Client Credentials.

Client secret

The app's General tab, under Client Secrets.

Ploy stores the client secret encrypted and never shows it again. To rotate it, create a new secret in Okta and paste it into Client secret. Leaving the field empty keeps the saved secret.

The Okta domain must be your Okta address, ending in okta.com, oktapreview.com, okta-emea.com, okta-gov.com or okta.mil. A custom domain such as login.acme.com is not accepted.

Test it

  1. Open your portal address, for example https://<your-portal-subdomain>.employee-access.com. You can find it under Portal URL on Settings → Portal config.

  2. Click Login with Okta and sign in with an Okta account that is assigned to the app.

  3. If you set up the tile, also open Ploy from the Okta End-User Dashboard.

What employees see

The portal's login page shows a Login with Okta button next to any other login options you turned on.

Okta sign-in is for the employee portal. The Ploy browser extension and Ploy Desktop don't offer Okta yet, so keep Google or Microsoft turned on if your employees use them.

To turn Okta sign-in off, click Okta under Login Options again and click Save. Ploy keeps the saved Okta details, so you can turn it back on without entering them again.

Fix sign-in errors

What the employee sees

What to check

"Invalid authentication request. Please try again"

PKCE or DPoP is ticked in Okta, or the client ID or client secret in Ploy is wrong. Okta's System Log shows the exact reason.

An Okta error about the redirect_uri parameter

The Sign-in redirect URIs in Okta must exactly match the Sign-in redirect URI shown in Ploy.

Okta says the user is not assigned to the client application

Assign the person, or a group they belong to, on the app's Assignments tab.

"No valid account found. Please contact your IT or security team to resolve this issue."

The email Okta returns doesn't match an employee in your Ploy organization.

"Okta login is not enabled for this organization"

Okta is off under Login Options, or the settings were not saved.

"Okta sign-in needs your portal address. Open it from your organisation's portal page."

Start from your portal address or the Okta tile, not a saved Okta link.

Was this helpful?
Was this helpful?