Okta Universal Logout

Okta Universal Logout signs users out of DataGrail right away when an Okta admin ends their sessions, for example after a compromised account or a risk alert from Okta Identity Threat Protection. Without it, an existing DataGrail session stays active until it expires on its own.

Requirements

Before you set up Universal Logout, confirm the following:

Requirement	Details
Single sign-on	Okta is your SAML or OIDC identity provider for DataGrail. See Configuring Okta For SSO or Configuring OIDC For SSO.
Okta plan	Your Okta org is on Okta Identity Engine with Adaptive MFA or Identity Threat Protection.
DataGrail role	You have the Super Admin role.
App assignment	Users are assigned to the DataGrail app in Okta, directly or through a group.
SAML signing	If you use SAML, the Okta app signs assertions with SHA-256. Universal Logout doesn't work with SHA-1.
Matching users	Users are matched by email address, so a user's Okta email must match their DataGrail email.

Federation Broker Mode Isn't Supported

Okta doesn't support Universal Logout for custom SAML and OIDC apps that have Federation Broker Mode turned on. Turn it off for the DataGrail app and assign users explicitly instead. See Okta's known issues for Federation Broker Mode.

Collecting Values

DataGrail verifies each logout request against an Issuer and a Subject that you enter in DataGrail. The values depend on whether the DataGrail app in Okta uses SAML or OIDC.

Value	SAML app	OIDC app
Issuer	The Issuer in the app's SAML details, for example http://www.okta.com/exkXXXXXXXXXXXXXXXXX. In Okta, open the app, select the Sign On tab, select More details under SAML 2.0, and copy the Issuer. It's not your Okta org URL.	Your Okta org URL, for example https://acme.okta.com. Don't use a custom authorization server URL.
Subject	The app's App instance ID, for example 0oaXXXXXXXXXXXXXXXXX. It appears in the Admin Console URL when you open the app. It's not the exk ID that appears in SAML URLs.	The app's Client ID.

Setting Up

Follow these steps to turn on Universal Logout. You copy a URL from DataGrail into Okta, then bring the values from Okta back to DataGrail.

1. In DataGrail, navigate to Settings and select Security.
2. Select the Okta Universal Logout tab and copy the Receiver URL.
3. In the Okta Admin Console, open your DataGrail app and find the Logout section on the General tab.
4. Enable Okta system or admin initiates logout.
5. Paste the Receiver URL into Endpoint URL.
6. Set Subject format to Email Identifier, then select Save.
7. Back in DataGrail, enter the Issuer and Subject from the table above, then select Save Changes.

Once saved, the tab shows an Enabled status. To turn Universal Logout off, select Disable.

Can't See the Tab?

If you don't see the Okta Universal Logout tab under Settings > Security, contact support@datagrail.io.

Triggering Logout

Okta only sends a logout request to DataGrail for certain actions. This table shows which actions sign a user out.

Action in Okta	Signs the user out of DataGrail?
Clear sessions and revoke tokens with Clear "keep me signed in", and include Logout enabled apps and Okta API tokens selected	Yes
Identity Threat Protection policy actions and user status changes, as configured in Okta	Yes
Clear sessions and revoke tokens without the Logout enabled apps option	No, only Okta sessions end
Unassigning the user from the DataGrail app	No

When a request is accepted, all of the user's DataGrail sessions end and their Remember me sign-in stops working. The user is signed out the next time they interact with DataGrail. Signing in again afterward works normally.

Each accepted request is recorded in the Security Audit Log as a Permission entry for the affected user.

Troubleshooting

Use the following items to resolve common problems.

Clearing a user's sessions in Okta doesn't sign them out of DataGrail

Check each of the following:

• Federation Broker Mode is turned off for the DataGrail app, and the user is explicitly assigned to it.
• You selected the option that includes Logout enabled apps when clearing sessions.
• The Endpoint URL in the Okta Logout section matches the Receiver URL shown in DataGrail, and the Subject format is Email Identifier.
• The user was signed in to DataGrail through this Okta app.

Okta reports that the request to DataGrail failed

The response code in the Okta System Log shows the cause:

Response	Cause
401	The Issuer or Subject in DataGrail doesn't match the values Okta sends, or the Endpoint URL doesn't match the Receiver URL. For a SAML app, a common cause is entering your Okta org URL as the Issuer instead of the app's SAML Issuer. Re-check the values in Collecting Values.
403	Universal Logout isn't set up in DataGrail, or the Endpoint URL uses a host DataGrail doesn't recognize.
404	No DataGrail user has the email address Okta sent.

I can't save my Issuer

For an OIDC app, the Issuer must be your Okta org URL with no path, for example https://acme.okta.com. For a SAML app, it must be the Issuer from the app's SAML settings, in the form http://www.okta.com/ followed by the app's ID. Both Issuer and Subject are required to save.

My SAML app uses SHA-1

Universal Logout doesn't work when the Okta app signs SAML assertions with SHA-1. In Okta, open the app, select Sign On, and make sure the active SAML signing certificate uses SHA-2.