Introduction

1. Welcome to this guide

Web Single Sign-On (SSO) is an authentication model that allows users to login into their remote machines using only one set of credentials. It also makes configuration much easier as it does not require any setup on the user's machine to connect to the server. It works using tokens granted by the Identity Provider after the user logged-in via browser.

You can implement that by linking with your current Active Directory environment, create a new one or use it without AD, in accordance with your Company's requirements. Analyzing pro and cons of these setup is however beyond the scope of this document.

NoMachine v10 supports OAuth2.0 + OIDC protocols and the following Identity Providers: Microsoft Entra ID (formerly Azure Active Directory or Azure AD), Okta, Keycloak and Google Identity.

Shortening and Keywords
SSO – Single Sign-On
OIDC – OpenID Connect
OAuth2.0 – Open Authorization 2.0
AD – Active Directory
IdP - Identitity Provider

Configurations

2. Configure OAuth2.0+OIDC and the IdP

Depending on the IdP, there can be several differences in their configuration and what they offer. NoMachine supports some basic features across the mentioned Identity Providers and all security improvements which are universal among them. Options unique or specific to a provider, are not supported yet.

This document is intended to provide general guidelines and some examples that can be useful to Administrators to setup their environment. It cannot however provide step-by-step instructions since they can greatly vary from one setup to the other.

General steps of configurations are:

1) Create OAuth Web application (known as 'Confidential Client') in your IdP.
Make sure that your OAuth client is set to 'Web' or ‘Confidential’.

2) Make sure that your OAuth client has the PKCE extension turned on and the Rotation of Tokens enabled, if available.

Google IdP use always the same token, for Okta you need to choose “rotate_token” for generating a new one, for Azure and Keycloak a new token will be generated by default.

3) Create the sso.cfg configuration file in:

(Linux) /usr/NX/etc
(macOS) /Applications/NoMachine.app/Contents/Frameworks/etc/
(Windows) C:\Program files\etc\

On Windows the sso.cfg file may be placed in a different drive than C:, the program will reiterate each drive from
letter A: to Z: to search for it.

You can find some examples of the sso.cfg file in the correspondent paragraph.

4) Add the server machine IP / domain as redirect URI to sso.cfg, based on Identity Provider documentation. The Identity Provider will accept this as a target to send data to.

5) Sign-in redirect URIs need to use this format:
https://(Your server IP / hostname)/?a=authcode&

2.1. Provider-specific Guides

To configure the IdP of your choice, we recommend to refer to their official guides.You can find below some indicative links.

Okta
https://developer.okta.com/docs/guides/implement-oauth-for-okta/main

Microsoft Entra ID
https://cloudtips.nl/configure-entra-id-authentication-for-azure-web-apps-9a80cf8aa296

Information about flow
https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow

Google Identity
https://support.google.com/googleapi/answer/6158849?hl=en#zippy=%2Cstep-create-a-new-client-secret%2Cstep-configure-your-app-to-use-the-new-secret

Keycloak
Guide https://www.keycloak.org/docs/latest/server_admin/index.html

or to create a client credentials
https://wkrzywiec.medium.com/create-and-configure-keycloak-oauth-2-0-authorization-server-f75e2f6f6046

2.2. The sso.cfg configuration file

The configuration file sso.cfg is made of two parts:
(i) the identifier part and
(ii) the config part.
The identifier part always needs to have 4 values, see the table below.
Fields required for the config part are grouped by those for OAuth and those for NoMachine.

Identifier part

Config part (OAuth)

This part of your SSO configuration is essential to correctly using OAuth protocol. All of these values are provided via IdP admin page or are well-known endpoints.

Config part (NoMachine)

^*1 For Google IdP, it is always the same token, for Okta you need to choose “rotate_token” for generating a new one, for Azure and Keycloak a new token will be generated by default.

2.3. Some examples of sso.cfg file

Examples below are with only the required fields, other optional fields will have their default value.

You can use “//” for comments to clarify some points.

Example 1

This is a minimal SSO configure file for 1 provider:

[    
  {
        "name": "Microsoft",
        "desc": "Example configure for Microsoft",
        "type": "OAuth",
        "provider": "microsoft",
        "config": {
            "idp_domain": "https://login.microsoftonline.com/(You-domain-ID)",
            "client_id": "(Your client ID)",
            "client_secret": "(You client secret)",
            "redirect_uris": ["https://(Server IP):4443/?a=authcode&"],
            "nx_user_type": "local",
            "nx_refresh": true,          // If you want refresh when logging again
            "nx_refresh_lifetime": 1200  // If you want refresh when logging again
        }
    }
]

Example 2

This is an example of SSO configure file for 3 providers:

[
    {
        "name": "Microsoft",
        "desc": "Example configure for Microsoft",
        "type": "OAuth",
        "provider": "microsoft",
        "config": {
            "idp_domain": "https://login.microsoftonline.com/(Your-domain-ID)",
            "client_id": "(Your client ID)",
            "client_secret": "(Your client secret)",
            "redirect_uris": ["https://(Server IP):(Web Port)/?a=authcode&"],
            "nx_user_type": "domain",
            "nx_refresh": true,
            "nx_refresh_lifetime": 1200
        }
    },
    {
        "name": "Okta",
        "desc": "Example configure for Okta",
        "type": "OAuth",
        "provider": "okta",
        "config":{
            "idp_domain": "https://(Your domain).okta.com",
            "client_id": "(Your client ID)",
            "client_secret": "(You client secret)",
            "redirect_uris": ["https://(Server IP):(Web Port)/?a=authcode&"],
            "nx_user_type": "local",
            "nx_refresh": true,
            "nx_refresh_lifetime": 1200
        }
    },
    {
        "name": "Google",
        "desc": "Example configure for Google",
        "type": "OAuth",
        "provider": "google",
        "config": {
            "idp_domain": "https://accounts.google.com",
            "client_id": "(Your client ID)",
            "client_secret": "(You client secret)",
            "redirect_uris": ["https://(Your server public domain)"],
            "nx_user_type": "local",
            "nx_refresh": true,
            "nx_refresh_lifetime": 1200
        }
    }
]

2.4. NoMachine settings for the sso.cfg file

Supported features are at the moment:

Centralized session and token system
If refresh token is revoked on IdP level, NoMachine will automatically fail when connecting in refresh mode. Remember that some IdP require token removed in administrator panel as they do not remove them when changing user policies/access.

Multi-tenant and registration flexibility of server
Multiple configurations on NoMachine servers allow to have multiple OAuth applications in IdP with different policies. It improves management of users and groups in complex environment.

Zero local credential management
Our application never stores client credentials locally on clients or servers. It keeps only granted tokens by IdP.

MFA on IdP level
Since access is handled by IdP, you can configure everything that is supported by your IdP.

No exposure of credentials
PKCE (Proof Key for Code Exchange) increases security by not sending client_secret into NoMachine clients, this is limiting possibility for interception of key.