# Single sign-on with Okta

> Page: https://docs.plotwork.dev/single-sign-on-okta. Index of every page: https://docs.plotwork.dev/llms.txt

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](https://docs.plotwork.dev/single-sign-on.md) describes.

## TL;DR

| Plotwork field | Where it comes from in Okta |
|---|---|
| Issuer URL | Your Okta domain, such as `https://acme.okta.com`. With a custom authorization server, its issuer, such as `https://acme.okta.com/oauth2/default`. |
| Client ID | The app's General tab, Client Credentials, Client ID |
| Client secret | The app's General tab, Client Credentials, the secret under Client secrets |
| Redirect URI to give Okta | `https://api.plotwork.dev/auth/sso/callback` |
| SAML: Single sign-on URL and Audience URI to give Okta | The ACS URL and the Entity ID on Plotwork's Single sign-on tab |
| SAML: Metadata URL | The 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 field | Value |
|---|---|
| App integration name | `Plotwork` |
| Grant type | Authorization Code only |
| Sign-in redirect URIs | `https://api.plotwork.dev/auth/sso/callback` |
| Sign-out redirect URIs | Leave empty |
| Controlled access | The groups that should be able to sign in to Plotwork |

4. 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 field | Value |
|---|---|
| Issuer URL | `https://<your Okta domain>`, the address you sign in to the Admin Console with, without `-admin` |
| Client ID | The Client ID you copied |
| Client secret | The secret you copied |

4. 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 field | Value |
|---|---|
| Single sign-on URL | The 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 format | EmailAddress |
| Application username | Email |
| Response | Signed |
| Assertion Signature | Signed |
| Signature Algorithm | RSA_SHA256 |
| Assertion Encryption | Unencrypted |

4. Press Next, then Finish. On the app's Sign On tab, under SAML Signing Certificates, copy the Metadata URL of the active certificate.
5. In Plotwork, paste it under Metadata URL, leave Email attribute empty, and press Save provider. Then turn on Sign in with single sign-on.
6. 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 field | Value |
|---|---|
| SCIM connector base URL | The SCIM base URL from Plotwork |
| Unique identifier field for users | `userName` |
| Supported provisioning actions | Push New Users, Push Profile Updates, Push Groups |
| Authentication Mode | HTTP Header |
| Authorization (Bearer) | The token from Plotwork |

4. Press Test Connector Configuration, then Save.
5. Under Provisioning, To App, press Edit and turn on Create Users, Update User Attributes and Deactivate Users, then Save.
6. 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 see | What 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 domain | The 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 dashboard | The person started from the Okta tile. Start from Plotwork's sign-in page instead. |

## See also

| Page | Why |
|---|---|
| [Single sign-on](https://docs.plotwork.dev/single-sign-on.md) | Domains, the switches, Require single sign-on and the way back in |
| [Single sign-on with Microsoft Entra ID](https://docs.plotwork.dev/single-sign-on-entra-id.md) | The same for Microsoft Entra ID |
| [Single sign-on with Google Workspace](https://docs.plotwork.dev/single-sign-on-google-workspace.md) | The same for Google Workspace |