Set up Okta for SSO and SCIM

This guide connects Onplana to Okta in two parts: SAML single sign-on, so people sign in to Onplana with their Okta account, and SCIM 2.0 provisioning, so Okta creates, updates and deactivates their Onplana accounts. You can set up SAML alone, or both.

The values in this guide are the same whether you add Onplana from the Okta Integration Network (OIN) catalog or create your own SAML app in Okta. Where the two differ, the step says so.

Prerequisites

• An Onplana plan with SSO and SCIM. Both are included in the Enterprise and Enterprise+ plans.
• An Onplana Owner or Admin for the Onplana side, and an Okta administrator who can add applications (Super Administrator or Application Administrator) for the Okta side.
• Your Onplana organization slug. It is the short name in your Onplana web address and on the SSO tab, for example acme in https://api.onplana.com/api/sso/acme/metadata. Every Onplana URL below uses it in place of <your-org-slug>.
• Your verified email domains. Onplana only signs in or provisions people whose email domain is on your organization’s verified domain list (set on the SSO tab). Have the list ready before you start.

Supported features

SAML 2.0 single sign-on

• SP-initiated SSO: sign in from Onplana’s sign-in page with your organization slug, which sends you to Okta and back.
• IdP-initiated SSO: sign in from the Onplana tile on the Okta End-User Dashboard.
• Just-in-time provisioning: a person signing in for the first time gets an Onplana account at the default role you choose, when their email domain is verified. You can switch this off and rely on SCIM instead.

SCIM 2.0 provisioning (Okta to Onplana)

• Create users: assigning a person to the app in Okta creates their Onplana account and adds them to your organization.
• Update user attributes: changes to name and email in Okta reach Onplana.
• Deactivate users: unassigning a person, or deactivating them in Okta, deactivates their membership in your Onplana organization. Their work is kept, and reassigning them restores the membership with the role they had.
• Import users: Okta can read your existing Onplana members to match them to Okta users.
• Group push (optional): pushing an Okta group named Members, Managers or Admins sets the Onplana role of its members.

Not supported: single logout, password sync (Okta’s password is never stored in Onplana), and deleting people (Okta deactivates; it never deletes).

Configure SAML single sign-on

Step 1. Add the app in Okta

1. In the Okta Admin Console, go to Applications, then Applications.

2. From the OIN catalog: select Browse App Catalog, search for Onplana, select Add Integration, enter your Onplana organization slug in Organization slug, and select Done. Okta fills in the SAML values from the slug; go on to Step 2.

   Without the catalog app: select Create App Integration, choose SAML 2.0, name the app Onplana, and on Configure SAML enter these values:

   Okta field	Value
   Single sign-on URL (Assertion Consumer Service URL)	https://api.onplana.com/api/sso/<your-org-slug>/saml/callback
   Use this for Recipient URL and Destination URL	selected
   Audience URI (SP Entity ID)	https://api.onplana.com/api/sso/<your-org-slug>
   Default RelayState	leave empty
   Name ID format	EmailAddress
   Application username	Email
   Update application username on	Create and update

   Under Show Advanced Settings, keep Response set to Signed and Assertion Signature set to Signed (Okta’s defaults), with signature algorithm RSA-SHA256.

   Under Attribute Statements, add three (name format Unspecified):

   Name	Value
   email	user.email
   firstName	user.firstName
   lastName	user.lastName

   Finish the wizard.

Step 2. Copy three values from Okta

On the app’s Sign On tab, under SAML 2.0, open More details (or View SAML setup instructions) and copy:

Value in Okta	Field in Onplana
Sign on URL (Identity Provider Single Sign-On URL)	IdP Single Sign-On URL
Issuer (Identity Provider Issuer, http://www.okta.com/...)	IdP Entity ID (Issuer)
Signing Certificate (download it, then open the file)	IdP X.509 Certificate

Step 3. Configure Onplana

1. In Onplana, open Apps and integrations in the sidebar (under Settings) and select the SSO tab.

2. Choose the SAML 2.0 tile. (The Okta tile is for Okta over OIDC.)

3. Paste the three values from Step 2. Paste the whole certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

4. Add your verified domains and choose the Default role for new SSO users (Member or Portfolio Manager).

5. Switch Single Sign-On on and select Save SSO Configuration.

No attribute mapping is needed in Onplana: it reads email, firstName and lastName as sent above, and falls back to the Name ID for the email.

Step 4. Assign people and test

1. In Okta, open the app’s Assignments tab and assign a pilot user.

2. IdP-initiated: sign in to the Okta End-User Dashboard as the pilot user and select the Onplana tile. You land in Onplana, in your organization.

3. SP-initiated: in a private window, open https://app.onplana.com/login?sso=<your-org-slug> (or choose Sign in with SSO on the sign-in page and enter the slug). Onplana sends you to Okta and back. The direct address https://api.onplana.com/api/sso/<your-org-slug>/initiate does the same.

4. Check the pilot user on the People page. Each sign-in is recorded in the audit log as SSO_LOGIN.

Note

Password sign-in stays available after SSO is on, so nobody is locked out while you roll it out.

Configure SCIM provisioning

Set up SAML first: SCIM uses the same verified domain list.

Step 1. Create a SCIM token in Onplana

1. Open Organization Settings, go to Security & Compliance, and on the Controls sub-tab find Automatic user provisioning (SCIM) in Provisioning and tokens.

2. Select Generate Token. Copy the token and the endpoint URL, https://api.onplana.com/scim/v2/<your-org-slug>. The token is shown once; store it in your password manager until you paste it into Okta.

Step 2. Turn on provisioning in Okta

1. Without the catalog app only: on the app’s General tab, select Edit under App Settings, set Provisioning to SCIM, and save. A Provisioning tab appears.

2. On the Provisioning tab, under Integration, select Edit (in the catalog app, Configure API Integration, then Enable API integration) and enter:

   Okta field	Value
   SCIM connector base URL	https://api.onplana.com/scim/v2/<your-org-slug> (the catalog app builds it from your slug)
   Unique identifier field for users	userName
   Supported provisioning actions	Push New Users, Push Profile Updates, Import New Users and Profile Updates; Push Groups if you will use group push
   Authentication Mode	HTTP Header
   Authorization (Bearer)	the token from Step 1

3. Select Test Connector Configuration (or Test API Credentials), then Save.

4. Under Provisioning, select To App, then Edit, and enable Create Users, Update User Attributes and Deactivate Users. Leave Sync Password off. Save.

5. Under Attribute Mappings, keep Okta’s defaults for userName (Email), givenName, familyName, email and displayName.

Step 3. Assign people, and optionally push groups

1. Assign people or groups on the Assignments tab. Each person assigned becomes an Onplana member at the Member role.

2. To set roles from Okta (optional): on the Push Groups tab, push an Okta group named Managers or Admins (or Members). Its members get that Onplana role, and a person removed from the group goes back to Member. Groups with any other name are accepted and change nothing.

3. Check the result in Onplana on the People page, and in the audit log (SCIM_USER_PROVISION, SCIM_USER_UPDATE, SCIM_USER_DEACTIVATE).

Deactivation is per organization: when Okta deactivates someone, only their membership in your organization is suspended. If they also belong to other Onplana organizations, those memberships are untouched. See Provision users with SCIM for how deactivation and reactivation keep work and roles.

Troubleshooting

What you see	Cause and fix
Okta: “Email domain ‘example.com’ is not in this organization’s verified SSO domain list”	The person’s email domain is not verified in Onplana. Add it on the SSO tab, then retry the assignment in Okta.
Okta: “SCIM provisioning requires an Enterprise plan”	The organization is not on Enterprise or Enterprise+.
Okta: “Invalid SCIM bearer token”, or Test Connector Configuration fails	The token was rotated or mistyped. Generate a new token in Onplana and paste it into the Okta app.
Okta: “User already exists in this organization” (409) when assigning	The person is already a member. Okta matches them by userName when you import users; run Import on the app’s Import tab first.
Okta shows HTTP 429	More than 120 SCIM requests a minute reached your organization. Okta retries on its own; large first imports finish over a few minutes.
Onplana sign-in: “SSO sign-in failed” with “Invalid document signature”	Okta is not signing both the Response and the Assertion, or the certificate in Onplana is not the app’s current signing certificate. Set both to Signed and paste the certificate again.
Onplana sign-in: “SSO sign-in failed” with “SAML assertion audience mismatch”	The Audience URI in Okta is not https://api.onplana.com/api/sso/<your-org-slug>. Correct it in Okta.
Onplana sign-in: “Your email domain is not on this organization’s verified domain list”	Add the domain on the SSO tab.
Onplana sign-in: “This organization requires accounts to be provisioned before first SSO sign-in”	Just-in-time provisioning is off and the person is not yet a member. Assign them in Okta with SCIM on, or turn JIT on.
New people are named after their email address	The firstName and lastName attribute statements are missing from the Okta app. Add them as in Step 1 of the SAML setup.
A name reads as changed on every sync	Onplana keeps one name and splits it at the first space, so a first name of two words (“Mary Ann”) comes back split differently. Nothing is lost; Okta resends the name.

For more sign-in messages, see Configure single sign-on.

Get help

Email support@onplana.com with your organization slug, the time of the failed sign-in or provisioning event, and the message Okta or Onplana showed.

Related

• Configure single sign-on, every SSO setting and sign-in message
• Provision users with SCIM, roles and per-organization deactivation
• Read audit logs, SSO and SCIM events