Configuring OIDC authentication

You can configure HTTP access services such as HCL Nomad to use OpenID Connect (OIDC) authentication rather than LDAP authentication or local authentication. Starting with HCL Safelinx 1.4.5, OIDC configuration includes support for bearer token authentication.

Before you begin

Configure the HTTP access service you will enable for OIDC. For HCL Nomad instructions, see Nomad server in the Nomad administration documentation.

About this task

OIDC authentication delegates user authentication to an OIDC identity provider (IdP) such as the Domino OIDC provider. When OIDC is configured, users log on to an HTTP access service using their OIDC IdP identities.

To configure OIDC authentication for an HTTP access service with bearer token support, complete the following steps across your SafeLinx Gateway and Domino Server.

Procedure

  1. Install OIDC Service Provider support (Linux only)
    Note: OIDC Service Provider support is installed automatically on Windows.
    On Linux, you can choose to install SafeLinx OIDC support by selecting "y" (yes) at the prompt Install OIDC Service Provider support? To install support for OIDC after SafeLinx installation from the installer archive, run the following command:
    Bash
    sudo rpm -ivh HCLSafeLinx-oidc-<safelinxversion>.rpm

    For example: sudo rpm -ivh HCLSafeLinx-oidc-1.4.4.rpm

  2. SafeLinx Configuration (The Gateway)

    SafeLinx serves as the entry point and must be configured to handle the OIDC handshake. The OIDC service can only be started if the oidc.config.yml file is present and properly configured.

    1. Update Configuration File: Modify the oidc.config.yml file to include the required OIDC provider, OIDC client, and the specific SafeLinx service port details. You can find an example file with all required details at <SafeLinx installation path>/oidc/oidc.config.example.yml.
    2. Define Credential Challenge: In the SafeLinx Administrator, navigate to the Mode tab. Set the Credential challenge type to OIDC IDP and ensure it points to the valid service provider address configured in the oidc.config.yml (the IDP URI and port must match the login_uri and port in the YAML file).
    3. Token Cookies: Set the SameSite token value to lax to prevent issues with missing or blocked cookies during the authentication flow.
  3. Domino Server Configuration

    These settings must be applied on the Domino server side to validate the tokens passed from SafeLinx:

    1. Internet Site Document: Create an Internet Site with a URL that matches the SafeLinx service URL (the port does not need to be specified here).
    2. Enable Bearer: In the Security tab of the Internet Site document, enable Bearer token.
    3. Certificate/SNI: Update the keyfile name to the correct certificate. Since Domino performs Server Name Indication (SNI) checks, it is a best practice to have the same SNI for both SafeLinx and the Internet Site.
    4. IdP Catalog (idpcat): In the idpcat.nsf, add an OIDC provider with a name corresponding to the Internet Site.
    5. OIDC Client: Create an OIDC client entry for the Internet Site within the catalog.
    6. Redirect URL: Set the redirect URL to: https://<SafeLinx server URL>:<port>/sl_oidc/callback.
    7. Audience: Set the audience field to: https://<SafeLinx server URL> (No need to specify the port name).
  4. Deployment & Verification
    1. Restart Service: Restart the SafeLinx server. If the oidc.config.yml is valid and contains all required inputs, the safelinx-oidc service will start automatically.
    2. Testing: Access the SafeLinx service URL. The system should successfully redirect you to the OIDC provider URL for authentication.