Skip to content
Connect an agent
Hosted diagrams and plans

Single sign-on with Okta

Connect an Enterprise organisation to Okta with OpenID Connect or SAML 2.0. Prove your email domain in Plotwork first, as the single sign-on guide describes.

TL;DR

Plotwork fieldWhere it comes from in Okta
Issuer URLYour Okta domain, such as https://acme.okta.com. With a custom authorization server, its issuer, such as https://acme.okta.com/oauth2/default.
Client IDThe app's General tab, Client Credentials, Client ID
Client secretThe app's General tab, Client Credentials, the secret under Client secrets
Redirect URI to give Oktahttps://api.plotwork.dev/auth/sso/callback
SAML: Single sign-on URL and Audience URI to give OktaThe ACS URL and the Entity ID on Plotwork's Single sign-on tab
SAML: Metadata URLThe app's Sign On tab, SAML Signing Certificates, the Metadata URL

1. Create the app integration

  1. In the Okta Admin Console, open Applications, then Applications, and press Create App Integration.
  2. Choose OIDC - OpenID Connect as the sign-in method and Web Application as the application type, then press Next.
  3. Fill in the form:
Okta fieldValue
App integration namePlotwork
Grant typeAuthorization Code only
Sign-in redirect URIshttps://api.plotwork.dev/auth/sso/callback
Sign-out redirect URIsLeave empty
Controlled accessThe groups that should be able to sign in to Plotwork
  1. Press Save.

2. Copy the values into Plotwork

  1. On the app's General tab, under Client Credentials, check that Client authentication is Client secret. You can also tick Require PKCE as additional verification: Plotwork always sends it.
  2. Copy the Client ID, and the secret under Client secrets.
  3. In Plotwork, open your organisation's Single sign-on tab and fill in Identity provider:
Plotwork fieldValue
Issuer URLhttps://<your Okta domain>, the address you sign in to the Admin Console with, without -admin
Client IDThe Client ID you copied
Client secretThe secret you copied
  1. Press Save provider, then turn on Sign in with single sign-on.

3. Check the address claim

Plotwork reads the email claim of the ID token, and refuses it when email_verified is false. Okta sends both when the app asks for the email scope, which Plotwork does. The address must be on a domain you verified in Plotwork: a person whose Okta address is on another domain is refused, and the failure is recorded.

Or connect with SAML 2.0

  1. In the Okta Admin Console, open Applications, then Applications, press Create App Integration, choose SAML 2.0, and press Next.
  2. Name the app Plotwork and press Next.
  3. In Plotwork's Single sign-on tab, choose SAML 2.0 under Identity provider, then fill in Okta's Configure SAML step from it:
Okta fieldValue
Single sign-on URLThe ACS URL from Plotwork. Leave Use this for Recipient URL and Destination URL ticked.
Audience URI (SP Entity ID)The Entity ID from Plotwork
Name ID formatEmailAddress
Application usernameEmail
ResponseSigned
Assertion SignatureSigned
Signature AlgorithmRSA_SHA256
Assertion EncryptionUnencrypted
  1. Press Next, then Finish. On the app's Sign On tab, under SAML Signing Certificates, copy the Metadata URL of the active certificate.
  2. In Plotwork, paste it under Metadata URL, leave Email attribute empty, and press Save provider. Then turn on Sign in with single sign-on.
  3. Assign the people or groups who should sign in on the app's Assignments tab.

People start from Plotwork's sign-in page. Starting from the Plotwork tile on the Okta dashboard is refused, because Plotwork accepts only sign-ins it started; hide the tile under the app's General tab, App Settings, Do not display application icon to users.

Provisioning with SCIM

  1. In Plotwork's Single sign-on tab, under Provisioning with SCIM, press Make token and copy the token and the SCIM base URL.
  2. In Okta, open the Plotwork app's General tab, press Edit under App Settings, set Provisioning to SCIM, and save. A Provisioning tab appears.
  3. On the Provisioning tab, under Integration, press Edit and fill in:
Okta fieldValue
SCIM connector base URLThe SCIM base URL from Plotwork
Unique identifier field for usersuserName
Supported provisioning actionsPush New Users, Push Profile Updates, Push Groups
Authentication ModeHTTP Header
Authorization (Bearer)The token from Plotwork
  1. Press Test Connector Configuration, then Save.
  2. Under Provisioning, To App, press Edit and turn on Create Users, Update User Attributes and Deactivate Users, then Save.
  3. On the Push Groups tab, push the groups you want Plotwork to see. In Plotwork, choose the role each gives under Groups and roles.

The SAML app and the OIDC app can both provision: use the one you sign in with.

Troubleshooting

What you seeWhat to check
"The issuer could not be used: the document names a different issuer"Use the issuer exactly as https://<your Okta domain>/.well-known/openid-configuration writes it, with or without /oauth2/default.
"Your identity provider did not sign you in"The person is not assigned to the app. Add them, or their group, under Assignments.
"Your identity provider sent a sign-in Plotwork could not trust"The Client ID in Plotwork is not this app's, or the issuer belongs to another authorization server. For SAML: the Single sign-on URL or the Audience URI is not Plotwork's, Assertion Encryption is on, or Okta rotated its certificate; save the provider again with the same Metadata URL.
Okta says a user could not be created: the address is not on a verified domainThe person's Okta username is on a domain you have not verified in Plotwork. Verify it, or change the username.
"The link has expired or was opened in another browser" after the Okta dashboardThe person started from the Okta tile. Start from Plotwork's sign-in page instead.

See also

PageWhy
Single sign-onDomains, the switches, Require single sign-on and the way back in
Single sign-on with Microsoft Entra IDThe same for Microsoft Entra ID
Single sign-on with Google WorkspaceThe same for Google Workspace