How to Configure OIDC Single Sign-On for Apps?

This article provides a comprehensive overview of the OpenID Connect (OIDC) protocol and offers a step-by-step guide to configuring an OIDC enterprise application within Hexnode IdP.

Understanding OIDC Authentication

OpenID Connect (OIDC) is a modern, lightweight authentication protocol built as an identity layer on top of the OAuth 2.0 authorization framework. While OAuth 2.0 was originally designed purely for delegating access (authorization), OIDC extends it to securely verify who the user is (authentication).

At the core of an OIDC transaction is the JSON Web Token (JWT). When a user logs in, the Identity Provider validates their credentials and issues a digitally signed JWT (specifically, an ID Token) to the client application. This token contains verified claims about the user’s identity, allowing the application to securely establish a session without ever seeing or storing the user’s actual password.

OpenID Connect in Hexnode IdP

Within your identity architecture, Hexnode IdP acts as the authoritative Identity Provider (IdP). When an application is integrated with Hexnode IdP using the OIDC protocol, traditional session-based authentication methods are replaced with secure, token-based communication.

Instead of authenticating directly against the application, the application redirects users to Hexnode IdP. Hexnode IdP securely handles the credential verification process. Upon successful login, it redirects the user back to the Service Provider (the client application) alongside signed JSON Web Tokens. This standardized process ensures that identity data is transmitted securely while maintaining seamless compatibility with contemporary development frameworks.

When to Use OIDC Authentication

OIDC is the preferred standard for modern application development. Because it utilizes lightweight JSON formatting and the robust OAuth 2.0 framework, it is highly efficient and developer friendly.

You should choose OIDC authentication when deploying:

• Single-Page Applications (SPAs): Browser-based front-end architectures built with frameworks like React, Angular, or Vue heavily rely on OIDC for secure token management without traditional backend session states.
• Mobile and Native Apps: OIDC is optimized for mobile environments, easily securely issuing and refreshing tokens for iOS, Android, or desktop applications.
• Modern API Architectures: When your infrastructure relies on microservices and API gateways, OIDC provides the ideal token-driven authentication layer to secure backend communications.

Configure OIDC SSO for apps from Hexnode IdP

The following steps outline how to initialize an OIDC application, define its security parameters and token behaviours, and finalize the integration in Hexnode IdP.

Step 1: Initialize the Application

First, create the application container within the portal.

1. Log in to the Hexnode IDP portal.
2. Navigate to Applications > MyApps.
3. Click + Add Apps.
4. Select OIDC as the protocol.
5. Click the edit icon next to Untitled Application to rename the application.
6. (Optional) Upload a logo for quick visual recognition.
7. Click Save.

Step 2: Configure OIDC Single Sign-On (SSO)

This section defines how your application communicates with Hexnode IdP, determining how tokens are issued, how users are redirected, and the level of security enforced.

Core Configuration

1. Select the Application Type that matches your architecture:
   1. Web Application: For server-side apps where backend code handles authentication logic.
   2. Native Application: For installed mobile or desktop applications.
   3. Single Page Application (SPA): For browser-based front-end applications.
2. Define the Client Type:
   1. Confidential: For applications that can securely store a Client Secret (typically server-side web apps).
   2. Public: For applications that cannot securely store secrets (such as mobile apps or SPAs).
3. Configure Require PKCE:
   1. Proof Key for Code Exchange (PKCE) prevents the interception and reuse of authorization codes.
   Note:

   If your Client Type is set to Public, PKCE is mandatory. The checkbox will be selected by default and greyed out.
   

Endpoints and Permissions

1. Define your Login Redirect URIs:
   1. Click + Add Redirect URI to specify the authorized endpoints where Hexnode IDP should send users after a successful authentication. If the redirect URI in an authentication request does not match a registered value here, the login will fail.
2. Define your Logout URIs:
   1. Click + Add Logout URI to define the destination where users are redirected after logging out, ensuring a controlled session termination.
3. Select your Allowed Scopes:
   1. Scopes define what identity information the application can request. Options include Open ID (Required), Profile, Email, Offline Access (allows issuance of refresh tokens), and SCIM.

Grant Types

1. Select the method your application uses to obtain access tokens from Hexnode IdP:
   • Authorization Code: The most secure and recommended flow. The user authenticates, an authorization code is sent to your application, and your application securely exchanges that code for tokens.
   • Refresh Token: Allows your application to request new access tokens without prompting the user to log in again, maintaining long-running sessions and improving user experience.
2. Click Next to proceed.

Step 3: Automate user lifecycle with SCIM 2.0 provisioning

If you wish to automatically sync user accounts between Hexnode IdP and the Service Provider, configure the SCIM connection parameters.

1. Provide the SCIM 2.0 Endpoint URL and the secure Authorization Token.
2. Select the required Provisioning Actions (Create Users, Update Users, Deactivate Users, Sync Groups).
3. Configure the Synchronization Schedule by setting a specific Schedule Sync time and Frequency (Daily, Weekly, or Monthly).
4. Configure the User Attribute Mapping and Group Attribute Mapping to align Hexnode IdP fields with the application’s required schema.
5. Click Next.

Step 4: Manage user and group assignments

In the Assignments section, define which identities are authorized to authenticate into the application. You can browse your directory and explicitly Include or Exclude specific users or groups to control access based on your organization’s requirements. After defining the initial access rules, click Next.

Step 5: Review the application

1. On the Review page, carefully verify the complete summary of your configuration, including:
   1. OIDC Single Sign-On settings
   2. SCIM provisioning configuration
   3. User and group assignments
2. If you need to make changes, click Edit next to the corresponding section.
3. Once verified, click Create to complete the setup.

After creation, the application is listed under Applications > My Apps, where you can manage it at any time.