Enable Okta SSO for Opaque¶

This guide walks you through integrating your Okta Identity Provider (IDP) with Opaque, which is backed by Auth0. This integration enables single sign-on (SSO), allowing users to access Opaque using their existing Okta credentials—eliminating the need for separate username and password management.

Before you begin¶

Before integrating with Opaque, ensure you have the following:

• Opaque callback URL and a global token revocation link (provided by Opaque).
• Okta account with administrator privileges.
• Access to create and configure applications in Okta.
• List of users who need administrative roles in Opaque.
• A secure email client to send sensitive details.

Integration overview¶

The following graphic captures the key steps involved in integrating Okta SSO with Opaque.

Integrating with Opaque¶

To integrate Okta with Opaque, you'll set up an OIDC web application in your Okta tenant, configure authentication settings, and assign users to an Opaque organization. In Opaque, organizations serve as top-level units for user management, with users assigned specific roles. If managing multiple organizations in Opaque, you’ll need to create a separate Okta app integration for each one.

Step 1. Add and configure the Opaque web app in Okta¶

1. Log in to your Okta Admin Console.
2. Click Applications > Create App Integration.
3. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type.

4. Click Next to configure the app settings.

   

5. Enter an App integration name (e.g., Opaque SSO), and fill in the Sign-in redirect URI provided by Opaque. This is where Okta sends OAuth responses.

   

6. (Optional; Okta Professional or Enterprise plans only) Enable Universal Logout to keep sessions in sync between Okta and Opaque.

   Note

   With Universal Logout enabled, signing out of Okta or deactivating an account logs the user out of Opaque within 10 minutes (the access token's TTL). Learn more about Universal Logout.

   To enable:

   • Use the global token revocation URL from Opaque.
   • Add it to the Logout endpoint URL field in your Okta app settings.
   • Click Save.

   

7. Configure Controlled access settings to define which groups of users can access the Opaque application.

   

8. Click Save to finalize the app integration.

Step 2. Share your app details with Opaque¶

Opaque uses Auth0 behind the scenes to connect with your Okta IDP. To complete the integration, you'll need to send Opaque your app’s credentials securely—including the client ID and client secret—along with your Okta domain and email domain. We recommend using Yopass, an open-source, secure web-based secret sharing tool that performs browser-side encryption to ensure your data never leaves your device unprotected.

Retrieve your Okta application details¶

1. In Okta, navigate to Applications and select your newly created Opaque app.

2. Locate and copy the Client ID and Client Secret—you’ll submit both values to Opaque using Yopass. Do not email them directly.

   

Submit your app details via Yopass¶

To securely share these sensitive values, use Yopass to generate a one-time encrypted message. Follow these steps:

1. Go to https://yopass.se and paste the following into the Secret message box. Replace the placeholders with your actual values:

   Customer name: <your name>
   Okta domain: https://<your-okta-domain>.okta.com
   Email provider domain of Okta accounts: <your org’s user email domain> (e.g., @example.com)
   Okta client ID: <your-okta-client-id>
   Okta client secret: <your-okta-client-secret>
   

2. Under Expiration settings, select One week to ensure availability during coordination.

3. Ensure both checkboxes are enabled:
   • One-time download
   • Generate decryption key
4. Click Encrypt message.
5. On the confirmation screen, copy the One-click link (recommended). This includes the decryption key and allows Opaque to retrieve the secret in a single access.

6. Reply to your original onboarding email from Opaque and paste the secure link in your message. We recommend using the subject line:

   Opaque Okta Integration – App Credentials

   You can include a short message such as:

   Hi Opaque team,
   
   Here is the secure link with our Okta app credentials for SSO integration:
   
   <Insert yopass link>
   
   <Your name>
   <Your company>
   

Opaque will notify you when the setup is complete, usually within one business day.

Step 3. Assign users to the app¶

Managing users through Okta groups simplifies administration, especially for large teams. You can create groups based on organizational divisions and assign them to Opaque. This guide shows you how to create a new group whose assigned users will have exclusive access to Opaque.

1. In your Okta tenant, go to Directory → Groups and click Add group.

2. Add a group name (e.g., Opaque users), an optional description, and click Save.

   

3. Select the newly created group, then click Assign people.

4. Click the + icon next to the users you want to add to this group. By default, they will be added as users without admin privileges.
5. Navigate to Applications → Your Opaque App.

6. Click Assign, and choose Assign to Groups.

   

7. Add your designated group of Opaque users to the app and click Done.

Step 4. Test and validate the integration¶

Before you can fully test and validate your integration, Opaque must add your designated administrator(s) to your Opaque organization.

1. Assign an organization admin. You need at least one admin who will manage your Opaque organization and users.

2. Have the admin(s) sign in to Opaque.

   Note

   Upon first sign-in, your designated org admin(s) will be treated as regular Opaque users without admin privileges.

3. After they’ve logged in, send the following details to your Opaque contact:

   • Admin name and email.
   • Confirmation that they’ve successfully signed in.

Once confirmed, Opaque will assign admin privileges, enabling them to manage your Opaque organization and users.

Verify user roles¶

To ensure Okta authentication is working correctly, ask two users—one with admin privileges and one without—to sign in to Opaque.

• Confirm successful authentication: Ensure users are redirected through Okta SSO and logged in to Opaque.

  • Admins should see Audit Log and Admin in the left-hand navigation bar after signing in.
  • Non-admin users should not see these navigation items.

  

• Validate admin permissions: Confirm that your org admin can manage users via the Admin settings. (See Managing users for details.)

Sign-in issues? Refer to the following troubleshooting table for common sign-in problems and solutions.

Troubleshooting sign-in issues¶

Need help?¶

• For Okta-related questions:
  • Refer to the Okta Help Center.
• For Opaque-related questions:
  • Refer to the Opaque documentation.
  • Contact Opaque support: [email protected].