Customer organization, OIDC, and license-user management guide

Understand the model

How the pieces relate

The word “organization” can refer to different data. Your Usakey workspace and the customer companies it manages (customer organizations) are separate.

Choose a setup

Choose a scenario

Choose the closest scenario and continue there. Scenarios 1 through 3 require the shared OIDC setup first.

Choose a setup · Scenario 0

Use device-bound licenses only

If access is managed with a license key and device rather than a user account, you do not need customer organizations, OIDC, or license users. This scenario is available on every plan.

1. In Policies, set “User identification method” to “License key (activate each device)”.
2. Issue a license from that policy.
3. Give the license key to the user and activate the device in the product app.

Configure · Shared preparation

Configure an OIDC connection

An OIDC connection lets software users authenticate with their company identity provider (IdPThe identity provider that manages company accounts and verifies identity, such as Microsoft Entra ID, Google Workspace, or Okta.) before entering the customer portal. It is available on Team and above. Microsoft Entra ID, Google Workspace, Okta, HENNGE One, CloudGate UNO, and GMO Trust Login are available as presets. Other providers with standard OIDC Discovery, such as Auth0, follow the same process.

1. Register a web app with the IdP

1. In the IdP, register a web app that has a Client Secret (some IdPs call it a web app using “Authorization Code Flow” or a “confidential client”).
2. Register this URL as an exact-match redirect URI.

Use the URL shown when this page is opened in production. A trailing slash, HTTP versus HTTPS, or a different host name makes the value different.

2. Reduce manual entry with presets and Discovery

Choose an IdP preset at the top of the connection form to see its preparation steps and cautions. The amount of endpoint data filled automatically depends on the provider.

“Load from Discovery” reads /.well-known/openid-configuration for the IssuerThe URL that identifies the IdP. It must exactly match the iss value in ID tokens. through Usakey’s server and fills the Authorization Endpoint, Token Endpoint, JWKS URI, scopes, and Client Secret method. It refuses a response whose issuer differs from the input or that contains a non-HTTPS endpoint or an endpoint on a port other than 443. Usakey connects to IdPs only over HTTPS on the standard port (443). Client ID and Client Secret are never filled automatically; enter the values issued by the IdP.

Google Workspace uses the shared issuer https://accounts.google.com. Issuers are unique within a workspace, so only one Google Workspace connection can be registered per workspace. You cannot register a separate Google connection for every customer organization. Set the Google OAuth consent screen to “Internal” when enabling JITJust-in-time provisioning: the license user is created automatically when the person first signs in to the customer portal. It does not create an assignment., otherwise personal Google accounts may authenticate.

3. Copy values from the IdP

For Microsoft Entra ID, use a tenant-specific endpoint whose ID-token iss is stable. Endpoints such as common and organizations, where the issuer can vary by user, do not work with Usakey’s exact-match verification.

4. Register it in Usakey

1. Open OIDC connections and choose “Add OIDC connection”.
2. If you use customer organizations, choose one as “Target customer organization”. For a workspace-wide connection, leave “All customer organizations / No customer organization”.
3. Choose an IdP preset and enter the tenant ID or Okta domain, or paste an issuer and choose “Load from Discovery”. For an unlisted IdP, enter the issuer and three endpoints manually.
4. Enter Client ID and Client Secret. Leave the Client Secret method at client_secret_basic unless the IdP requires otherwise.
5. Use openid profile email for Scopes in most cases. openid is required.
6. PKCEProtects sign-in so that a stolen authorization code cannot be used on its own. Always on in Usakey. (S256) is always used, so no action is needed. Choose whether to use JIT in the scenario below.
7. The oid_... shown as “Connection ID for users” after registration is the connection ID to give users.
8. Use “Test in the customer portal” in the OIDC connection details and confirm that the real IdP login returns successfully.

OIDC endpoints must be HTTPS URLs on port 443 resolving from public DNS to a global IP. For security, Usakey cannot connect to an IdP that resolves to an internal network address (private, loopback, or link-local). The dedicated-environment plan is not currently offered to new customers, and existing dedicated environments have the same restriction.

Configure · Scenario 1

Use company accounts for one company without customer organizations

This is the shortest small-team setup on Team and above. Use a shared OIDC connection without creating a customer organization. Because it still uses OIDC and the customer portal, Personal is not eligible.

Complete the shared OIDC setup first.

1. 1

   Policy

   Set “User identification method” to “User-based (assign user accounts)” and save.

2. 2

   OIDC connection

   Leave “Target customer organization” as “All customer organizations / No customer organization” and register a shared connection.

3. 3

   License

   Issue a license pool from the named-user policy.

4. 4

   First login

   With JIT enabled, a license user is created when the person first signs in to the customer portal with the connection ID.

5. 5

   User assignment

   Open “Manage assignments” on the license and assign the person.

6. 6

   Two-factor authentication

   The user sets up a passkey (recommended) or an authenticator app in the customer portal.

7. 7

   Product authentication

   The user issues an authentication token and enters it in the product app.

A JIT-created user has no assignment yet, so the portal displays “No licenses are assigned”. Ask the user to reload or sign in again after an administrator assigns access.

Configure · Scenario 2

Separate users and SSO for each customer company

This is the standard setup for managing multiple companies on Team and above. A customer organization is a directory boundary; it is different from the customer record that represents the recipient of a license.

Review the shared OIDC setup before registering each company’s IdP.

1. In Customer organizations, choose “Add customer organization” and enter the company name, external ID, and optional user limit.
2. From the customer organization details, choose “Add OIDC connection” and register that company’s IdP.
3. For manual registration, use “Add user” in the OIDC connection details. With JIT, wait for the user’s first login.
4. Use “Manage assignments” on the named-user license to assign the person.
5. Give the customer company the connection ID and customer-portal URL shown in the OIDC connection details.

Configure · Scenario 3

Choose JIT or pre-registration

Choose when to create user accounts after completing the shared OIDC setup.

Pre-register a user

1. Obtain the user’s stable sub from the IdP administrator. It is not an email address.
2. In License users, choose “Add user”.
3. Choose the OIDC connection to fill the issuer, then enter the IdP sub as Subject.
4. Create the assignment from the license details.

Configure · Scenario 4

Assign a license to a department or team

1. In the customer organization details, open “Groups” and choose “Add group”.
2. Add active users belonging to the same customer organization in the group details.
3. Open “Manage assignments” on the license.
4. Leave User empty and choose “Source group”.
5. Set an assignment expiry if needed and choose “Assign”.

Configure · Scenario 5

Use named-user licensing in a closed network

On Team and above, choose a managed fully offline policy tied to a user assignment and issue a signed use file valid for up to seven days. This is different from unmanaged offline perpetual licensing.

1. Issue a license from the named-user offline policy and assign it to the target user.
2. Create .usakeyreq on the target device and move it to the connected administrator device.
3. On the license details, choose “Use on a device that cannot connect to the Internet” and select “Target user assignment”.
4. Choose the .usakeyreq and press “Issue offline license file”.
5. Move the issued .usakeylic back to the target device and import it. For a named-user file, the product app passes the expected user and assignment when importing (see Fully offline devices).

Suspending a user or removing an assignment cannot take effect immediately while offline. The certificate expires within seven days, so issue a new file to continue. The customer-portal authentication token is not used when issuing this file.

Use and contract

Let a user verify and activate a product

This is the flow for a user starting the product app themselves. Local-ID users verify by email in the product app (Personal and above); OIDC users verify in the customer portal (Team and above). The device is activated after that.

Local-ID users: verify by email

• “Email license verification” on the license user's details in Console shows whether it can be used and, if not, why (no email address, no assignment, suspended, plan, and so on).
• The same email address cannot be registered to more than one local-ID user, because Usakey sends no code when it cannot tell which user is meant.
• Users who enrolled two-factor authentication are asked for a second code after the emailed code. Local-ID users cannot sign in to the customer portal, so set up their two-factor authentication on the license user's details.
• For passkeys, use “Ask to set up a passkey” on the license user's details to email the user a setup link (valid for 24 hours, one use). The user opens the link and registers a passkey, and the recovery codes are shown once.
• For passkey users, the verification code email links to a page that approves the check with the passkey. The page then shows an approval code, which the user enters in the product app's “authenticator app code or recovery code” field. The approval code works only for that check, for 10 minutes, once. No change to the product app or the SDK is needed.
• For an authenticator app, set it up on the license user's details and give the user the displayed information securely.
• When the conditions are not met, the product app receives the same response and no code is sent. The app cannot tell the reason, so check “Email license verification” above when a code does not arrive.
• The product app needs fields for the email address and the code (and the authenticator code). The official SDK's start_email_verification / confirm_email_verification (Node.js startEmailVerification / confirmEmailVerification; available in Rust, the C ABI, Node.js, Python, and Ruby) send the requests, verify the responses, and report results such as whether two-factor authentication is needed (twoFactorRequired). With bindings that lack these functions, the product app calls the Runtime API directly (Product app integration (Runtime API) steps).

OIDC users: issue an authentication token in the customer portal

This requires Team and above because it uses OIDC and the customer portal. Local-ID users use the email verification above.

1. Open the customer portal and enter the oid_... supplied by the administrator.
2. Choose “Continue with your organization's account”, go to the IdP, and sign in.
3. If “To issue an activation token, set up two-factor authentication.” appears, choose “Set up two-factor authentication” and set up a passkey (recommended) or an authenticator app.
4. Choose “Issue a five-minute activation token” on the assigned license and press “Copy”.
5. Paste it into the product app. The app combines it with the license key it already has and activates the device.

The two-factor authentication available in the customer portal is a passkey or an authenticator app (TOTPVerification with the six-digit code that an authenticator app shows every 30 seconds.). Multi-factor authentication at the IdP counts only when the OIDC connection sets trust_upstream_mfa to true in metadata. Then a user without two-factor authentication in the customer portal who signs in after multi-factor authentication at the IdP has two-factor authentication switched to the IdP, and later sign-ins require multi-factor authentication at the IdP every time. require_phishing_resistant_mfa accepts only key-based methods such as passkeys, and requested_acr_values asks the IdP for an authentication strength (Management API: update an OIDC connection).

Use and contract

License-type differences

Subscriptions, trials, and managed perpetual licenses consume different allowances and handle device activation differently.

When several users share a named-user trial: the first user’s first device activation starts the trial for the entire license. Assignments without an explicit expiry share the same end time. Issue one trial license per user if everyone must receive the full trial period from their own start date.

Operate · Lifecycle

Handle suspension, offboarding, and customer cancellation

After suspending or deactivating a user, or removing an assignment, the next online check rejects product use. Registered-device records and cloud-managed device allowances are not freed automatically. Remove unused devices with “Deactivate this device” in the customer portal or from Console.

Before operations that cannot be undone or have wide effect, such as suspending or revoking a license, forcibly deactivating a device, changing or stopping an OIDC connection or its client secret, or removing a license user's two-factor authentication, Console asks you to confirm your identity within the last 10 minutes (a verification code if you enrolled two-factor authentication, otherwise your password).

Operate · Maintenance

Rotate a Client Secret

1. Issue a new Client Secret at the IdP and, if possible, keep the old secret valid temporarily.
2. Open “Rotate Client Secret” in the OIDC connection details and enter the new value twice.
3. Choose “Switch to new secret”. Usakey immediately uses only the new secret.
4. Use “Test in the customer portal” in the OIDC connection details to perform a real login.
5. After success, revoke the old secret at the IdP.

Usakey does not keep old and new secrets simultaneously. If the IdP does not provide an overlap period, a short login interruption can occur during rotation.

Appendix

Troubleshooting

The user can sign in through JIT but sees no product

JIT creates only the user. An administrator must open “Manage assignments” on the license and grant access.

I do not know the connection ID

It is the oid_... value shown as “Connection ID for users” in the OIDC connection details, not the IdP Client ID.

OIDC login fails

Check exact Redirect URI, Issuer, Client ID, Client Secret, public HTTPS endpoints, and the ID-token sub, aud, and nonce.

Login fails with JIT disabled

Pre-register a user whose issuer and subject exactly match the IdP iss and sub.

There is no token button

A valid license assignment and completed two-factor authentication are required. Check the license, user, and assignment states.

The product rejects the token

It may be older than five minutes, belong to another license, have an assignment removed, or belong to a suspended user. Issue a new token (for email verification, verify again).

The verification email does not arrive

Check whether it can be used, and why not, in “Email license verification” on the license user details (registered email address, other local-ID users with the same address, assignment, suspension or deactivation, plan). The product app gets the same response when the conditions are not met, so the app screen cannot tell the difference.

A group member cannot see the product

Groups are not continuously synchronized. Run the group assignment again from the license assignment page.

Personal cannot add a customer organization or OIDC

This is expected. Use device-bound licensing or manage license users as local IDs; users activate by email verification in the product app. Move to Team or above when OIDC and the customer portal are required.

Two OIDC connections cannot use the same issuer

Issuers are unique within a workspace. Reuse one connection or configure a different issuer at the IdP.

The user did not receive instructions

Invitation emails are not automatic. Share the connection ID, customer-portal URL, and start instructions separately.

Appendix

Setup checklist

• The policy's identification method is “User-based (assign user accounts)”
• The OIDC Redirect URI matches exactly
• The customer portal can redirect to the IdP and return
• License users are active (not suspended or deactivated)
• The target license has an active assignment
• The user has completed two-factor authentication
• The product app has an authentication-token input (OIDC users)
• The product app has inputs for the email address and verification code (local-ID users)
• The device-removal process is defined for suspension and offboarding