Configuring the OIDC Discovery Endpoint for Identity Federation

The OpenID Connect (OIDC) Discovery Endpoint is the architectural “handshake” that allows Hexnode UEM to automatically configure itself for secure authentication and user synchronization. Instead of requiring IT admins to manually enter dozens of complex routing URLs (Authorization URL, Token URL, JWKS URI, etc.), Hexnode utilizes the IdP’s Discovery URL to automatically map the metadata required for identity federation.

In the Hexnode ecosystem, this OIDC architecture powers integrations with Microsoft Entra ID and Okta, enabling zero-touch enrollment authentication, Conditional Access, and Cloud Login (Hexnode Access).

1. Technical Specifications: The Discovery Architecture

The Discovery Endpoint provides a standardized JSON document containing the routing metadata necessary for Hexnode (acting as the Relying Party) to communicate with your Identity Provider (IdP).

Automated Discovery URL Patterns in Hexnode

Hexnode abstracts the manual entry of these URLs. By simply inputting your organizational identifiers into the Hexnode portal, the UEM automatically constructs and queries the following OIDC discovery endpoints:

2. Implementation Workflow: The Hexnode “Handshake”

Integrating your IdP with Hexnode relies on a secure OAuth 2.0 / OIDC flow. Here is how the endpoint interacts with Hexnode’s actual setup process (found under Admin > Integrations):

• Step 1: App Registration (IdP Side): Within your Entra ID or Okta admin console, you must register Hexnode as a web application. This generates the Client ID and Client Secret needed to authorize the API exchange.
• Step 2: Parameter Input (Hexnode Side): Instead of parsing JSON files, the admin inputs the App/Client ID, Client Secret, and Tenant ID/Domain into Hexnode.
• Step 3: Endpoint Retrieval & Token Exchange: Upon saving the configuration, Hexnode securely pings the IdP’s Discovery Endpoint. It fetches the Issuer, the Authorization Endpoint (where users see the login screen), and the JWKS URI (public keys for signature verification) to establish a persistent, trusted connection.

3. Required Scopes & API Permissions

To ensure that devices are correctly assigned to the right users and that OIDC tokens function correctly, specific scopes and API permissions must be granted to the Hexnode app registration within your IdP:

• openid: The foundational scope required for the OpenID Connect sign-in protocol.
• profile & email: Allows Hexnode to read the user’s basic profile data and map the enrolled device to the correct email address in the UEM directory.
• offline_access: Crucial for Hexnode Access and background syncing, allowing Hexnode to obtain refresh tokens so users aren’t constantly forced to re-authenticate.
• Directory.Read.All (Entra ID Specific): Microsoft Graph API permission required for syncing broader user groups and organizational units.

4. Operational Capabilities Powered by OIDC

Once the Discovery Handshake is complete, Hexnode unlocks several advanced identity-driven features:

• Authenticated Enrollment: During the initial setup of Windows, macOS, iOS, or Android devices, Hexnode uses the OIDC endpoints to redirect the user to the official Okta or Entra ID login screen. Credentials are processed directly by the IdP, ensuring Hexnode never stores plaintext passwords.
• Hexnode Access (Cloud Login): By leveraging OIDC, Hexnode allows users to sign into local Windows or macOS hardware using their cloud credentials. The Discovery Endpoint ensures the hardware continually syncs password changes from Okta or Entra ID down to the local machine login screen.
• Device Trust & Conditional Access: Hexnode acts as a compliance engine, passing the device’s management state back to Entra ID or Okta. If a device falls out of compliance, the IdP can block OIDC token generation for enterprise apps (e.g., Office 365, Salesforce).

5. Security & Verification Requirements

• TLS Requirement: All discovery routing and token exchanges between Hexnode and the IdP occur over encrypted TLS 1.2+ channels.
• JWKS Rotation: Hexnode periodically checks the jwks_uri found in the discovery document to update the public keys, ensuring that forged or expired identity tokens are rejected.
• Redirect URI Strict Matching: The Redirect URI provided in the Hexnode portal (e.g., https://{yourportal}.hexnodemdm.com/core/oidc/callback/) must be registered exactly within your Okta or Entra ID app. A single missing slash will cause the OIDC flow to fail with a mismatch error.

6. Troubleshooting Integration Failures

If the integration fails or users cannot authenticate, verify the following:

• Mismatched Tenant ID / Domain: Ensure the identifier entered in Hexnode exactly matches the one in your IdP, as this dictates the Discovery URL path.
• Expired Client Secret: In Entra ID, Client Secrets expire (typically after 6, 12, or 24 months). If the secret expires, the OIDC token exchange will fail until a new secret is generated and pasted into Hexnode.
• Missing Admin Consent: In Entra ID, ensure that “Grant admin consent for [Organization]” has been clicked for all requested API permissions.
• Okta API Token Validity: For Okta, ensure the API token tied to the integration has not expired or been revoked by a super admin.