How to configure Single Sign-On (SSO) with Okta

What you can do

Connect an Okta tenant to CRIBWISE Admin Portal as a SAML 2.0 identity provider, so your users sign in to Admin Portal with their Okta credentials.

The setup follows the same pattern as the general single sign-on guide, with three extra requirements that are specific to Okta: you upload CRIBWISE’s SAML signing certificate to Okta, you enable signed AuthnRequests, and you configure Single Logout (SLO).

Before you start

• You need Admin Portal access with permission to open Administration > System settings.
• You need administrator access to the Okta Admin Console, with permission to create app integrations.
• Every user who should sign in through Okta must already exist in Admin Portal, with an e-mail address that exactly matches their Okta account’s e-mail. See How to create and manage users.
• Those users must belong to a user group with the AP users role. Without it, authentication succeeds but Admin Portal refuses the login.
• All Admin Portal e-mail addresses must be unique. If two users share one, activation is blocked.

Warning: Once SSO is active, username and password login to Admin Portal is disabled. Keep Access for account administrators set to Allowed on the same Access control tab, so you retain a way in from the Customer Management Portal if the Okta configuration turns out to be wrong.

SSO covers Admin Portal only. Shop Floor Interface users keep signing in with their Admin Portal credentials, an RFID card, a barcode, or a Coges key.

Quick start

Experienced users — connect Okta in 5 steps:

1. In Admin Portal, open System settings > Access control > Set up SSO, copy the Entity ID and both consumer URLs, and click Download signature certificate.
2. In Okta, create a SAML 2.0 app integration and paste those values into Single sign-on URL and Audience URI.
3. Under Show Advanced Settings, upload the certificate, enable Single Logout, and enable Signed Requests.
4. Read the Okta metadata to get the IdP login URL, logout URL, and certificate thumbprint, then assign your users to the app.
5. Back in Admin Portal, fill in Login URL, Certificate thumbprint, and Logout URL, click Save settings, then Set active.

Need more detail? Follow the full steps below.

Which value goes where

Seven values move between the two systems. Putting one of them in the wrong field is the most common cause of a failed setup, so keep this table open while you work.

Important: Two different certificates are in play, in opposite directions. CRIBWISE’s certificate goes to Okta, so Okta can verify signed requests. Okta’s certificate thumbprint goes to Admin Portal, so Admin Portal can verify the assertion. Swapping them causes a redirect loop.

Steps

Step 1 — Collect the Admin Portal values

In the Admin Portal, go to Administration, select System settings, then open the Access control tab.

SSO lives on the Access control tab of System settings, not in its own menu entry.

Scroll to the bottom of the tab. The Single sign-on (SAML) section shows the current status — Not active until you finish this guide. Click Set up SSO.

(1) the Single sign-on (SAML) section and its status, and (2) the Set up SSO button that opens the panel.

The Single sign-on panel opens on the right. Its three lower rows are read-only and belong to your tenant — these are the values Okta needs.

1. Copy the Entity ID, the Login consumer URL, and the Logout consumer URL. Use the copy button at the end of each row.
2. Click Download signature certificate and save the .crt file.
3. Leave this panel open. You come back to it in step 4.

(1) the three read-only values to copy into Okta, and (2) the certificate Okta needs in order to validate signed requests.

Step 2 — Create the SAML app in Okta

1. In the Okta Admin Console, go to Applications > Applications.
2. Click Create App Integration.
3. Select SAML 2.0, then click Next.
4. On the General Settings step, enter a recognizable app name such as CRIBWISE SSO.
5. Click Next.
6. On the Configure SAML step, paste the Admin Portal Login consumer URL into Single sign-on URL.
7. Paste the Admin Portal Entity ID into Audience URI (SP Entity ID).
8. Leave Default RelayState, Name ID format, and Application username at their defaults, unless your organization has a specific requirement.
9. Expand Show Advanced Settings.
10. Leave Response and Assertion Signature set to Signed.
11. Next to Signature Certificate, click Browse files… and upload the .crt file from step 1.

Uploading the certificate is what unlocks the Enable Single Logout and Signed Requests options below. If those options look greyed out, the certificate has not been uploaded yet.

12. Select Allow application to initiate Single Logout.
13. Paste the Admin Portal Logout consumer URL into Single Logout URL.
14. Paste the Admin Portal Entity ID into SP Issuer — the same value you used for the Audience URI.
15. Select Validate SAML requests with signature certificates. Okta now verifies that every AuthnRequest from Admin Portal is signed with the certificate you uploaded.
16. Click Next.
17. On the Feedback step, choose This is an internal app that we have created, then click Finish.

Okta opens the new app’s detail page.

Step 3 — Read the Okta values and assign your users

1. On the app’s Sign On tab, scroll to SAML Signing Certificates and confirm that an active certificate is listed.
2. Open the app’s SAML metadata URL in a new browser tab. You find it under Sign On > View SAML setup instructions, or as Metadata URL on the Sign On tab. The address looks like this:

https://<okta-org>.okta.com/app/<app-id>/sso/saml/metadata

The metadata XML contains all three values you still need:

3. Compute the certificate’s SHA-1 thumbprint. Admin Portal expects 40 uppercase hexadecimal characters with no separators. Okta does not display this value, so derive it from the certificate — for example, in PowerShell:

$b64 = "<paste the base64 certificate from the metadata XML, no whitespace>"
$bytes = [Convert]::FromBase64String($b64)
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(,$bytes)
$cert.Thumbprint

4. Go to the app’s Assignments tab and click Assign > Assign to People.
5. Assign every Okta user who needs Admin Portal access.
6. Confirm that the username Okta sends matches the Admin Portal user’s e-mail address. The default is usually correct.

Important: The assignment step is easy to miss. Without it, Okta rejects the login with “User is not assigned to this application” — even though the SAML request and its signature validated correctly.

Step 4 — Finish the configuration in Admin Portal

1. Return to the Single sign-on panel you left open in step 1.
2. In Login URL, enter the Okta Identity Provider Single Sign-On URL.
3. In Certificate thumbprint, enter the SHA-1 thumbprint you computed in step 3.
4. In Logout URL, enter the Okta Identity Provider Single Logout URL.
5. Click Save settings.

(1) the three Okta values you enter, (2) Save settings, and (3) Set active. The values shown here are examples.

Click Set active. Admin Portal re-checks that every user e-mail address is unique, then shows this warning.

Read the warning before you continue. Cancel is safe — Proceed switches every Admin Portal user over to Okta.

Confirm that your users exist on both sides, then click Proceed.

Success: The status in the Single sign-on (SAML) section changes from Not active to Active. Admin Portal now redirects new sign-in attempts to Okta.

Step 5 — Test before you log out

Warning: Do not close your current Admin Portal session yet. It is your fastest way back if the configuration is wrong.

1. Keep your existing, authenticated Admin Portal window open.
2. Open a new private or incognito window and browse to your Admin Portal address.
3. Confirm that you are redirected to Okta, that you can authenticate, and that you land back in Admin Portal.
4. If the test fails, switch back to your original window and deactivate SSO from the same Set up SSO panel, then re-check your values.

A user signing in for the first time is asked to accept the Acceptable Use Policy, exactly as with any other login method.

Next steps

1. Review who can reach Admin Portal — check group membership and roles in the Admin Portal permissions reference.
2. Decide on account administrator access — turning it off closes the last non-SSO route into the portal. See the System settings reference.
3. Onboard new users in both systems — create the Admin Portal user, then assign them to the Okta app. A user who exists in only one system cannot sign in.

Troubleshooting

Related articles

• How to configure Single Sign-On (SSO) — the general SSO guide, with an Azure AD walkthrough.
• How to configure Single Sign-On (SSO) with Auth0 — the same setup against Auth0, which needs a SAML addon instead of a SAML app.
• How to create and manage users — create the Admin Portal users that Okta identities map onto.
• How to create and configure a user group — grant the AP users role that SSO logins require.
• Admin Portal permissions reference — what each role and permission controls.
• System settings reference — the rest of the Access control tab, including access for account administrators.
• How to log in to Shop Floor Interface — why Shop Floor Interface sign-in is unaffected by SSO.