NOM-7 SSO documentation

modules/ROOT/content-nav.adoc

@@ -11,6 +11,11 @@
 * xref:installation/index.adoc[]
 ** xref:installation/persistence.adoc[]
 ** xref:installation/server.adoc[]
+** xref:installation/sso/index.adoc[]
+*** xref:installation/sso/configuration.adoc[]
+*** xref:installation/sso/entra-id.adoc[]
+*** xref:installation/sso/google-identity.adoc[]
+*** xref:installation/sso/okta.adoc[]
 ** xref:installation/docker/index.adoc[]
 *** xref:installation/docker/container.adoc[]
 *** xref:installation/docker/compose.adoc[]

modules/ROOT/pages/installation/index.adoc

@@ -3,6 +3,7 @@
 
 * xref:./persistence.adoc[NOM Persistence DBMS] - Set up a DBMS for NOM to use
 * xref:./server.adoc[Server installation] - Install and configure NOM server on Windows or Linux
+* xref:./sso/index.adoc[Single Sign-On] - Configure Single Sign-On in NOM
 * xref:./docker/index.adoc[Docker] - Install NOM server using Docker
 * xref:./kubernetes/index.adoc[Kubernetes] - Deploy NOM server on Kubernetes
 * xref:installation/self-signed-certificate.adoc[] - Generate self-signed certificates for use with NOM

modules/ROOT/pages/installation/server.adoc

@@ -221,7 +221,7 @@ java -jar .\lib\server.jar
 [[self-registration-config]]
 [NOTE]
 ====
-If the NOM Server is required to support self-registered agents ensure that the configuration property `GRPC_SERVER_SECURITY_TRUST_CERT_COLLECTION` (or `grpc.server.security.trustCertCollection`) is provided to above commands.
+If the NOM Server is required to support self-registered agents ensure that the configuration option `GRPC_SERVER_SECURITY_TRUST_CERT_COLLECTION` (or `grpc.server.security.trustCertCollection`) is provided to above commands.
 It is described in the configuration reference table below.
 
 Read more about agent self-registration xref:../addition/agent-installation/self-registered.adoc#agent_mtls[here].
@@ -351,6 +351,106 @@ For details about configuring proxy in Java, see link:https://docs.oracle.com/en
 | `LOGGING_LEVEL_COM_NEO4J`
 | Log level of the `com.neo4j` logger (its output corresponds to what NOM server itself logs). Default: `info`. (optional)
 | `error`, `warn`, `info`, `debug` or `trace`
+
+| `logging.level.com.neo4j.opsmanager.server.config`
+| `LOGGING_LEVEL_COM_NEO4J_OPSMANAGER_SERVER_CONFIG`
+| Log level of the configuration logger. Setting it to `debug` is useful for troubleshooting SSO issues. Default: `info`. (optional)
+| `error`, `warn`, `info`, `debug` or `trace`
+
+
+| `app.sso.active-configurations`
+| `APP_SSO_ACTIVE_CONFIGURATIONS`
+| Lists comma-separated names of configurations that should be offered as login options on the NOM login page.
+| `myConfig1,myconfig2`
+
+| `app.username-password-login.enabled`
+| `APP_USERNAME_PASSWORD_LOGIN_ENABLED`
+| Username/password login can be enabled or disabled, enabling SSO login either be offered additionally or to be the only login method.
+If disabled, the pages "NOM Administrators" and "Profile" will not be available in the NOM UI.
+| `false`
+|===
+
+In the reference below, the placeholder `<CONFIG>` is used to indicate where the configuration name should be used (e.g. "myConfig1").
+
+
+[cols="<,<,<, <",options="header"]
+|===
+| Command line argument
+| Environment variable name
+| Description
+| Example value
+
+| `app.sso.configurations.<CONFIG>.idp-type`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_IDP_TYPE`
+| Type of the Identity Provider (IdP). Currently only `ENTRA_ID`, `GOOGLE_IDENTITY` and `OKTA` are supported.
+| `ENTRA_ID`
+
+| `app.sso.configurations.<CONFIG>.display-name`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_DISPLAY_NAME`
+| Display name of the login option on the NOM login page.
+| `Login with Entra ID`
+
+| `app.sso.configurations.<CONFIG>.admin-check`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_ADMIN_CHECK`
+| SpEL expression to check if the user should be assigned the NOM Admin role in NOM.
+See xref:/installation/sso/configuration.adoc#_role_assignment[Role assignment] for details.
+| `['groups']?.contains('aaa63d30-70c3-4181-8c19-1b58e613f55b')`
+
+| `app.sso.configurations.<CONFIG>.read-only-user-check`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_READ_ONLY_USER_CHECK`
+| SpEL expression to check if the user should be assigned the NOM Read-only administrator role in NOM.
+See xref:/installation//sso/configuration.adoc#_role_assignment[Role assignment] for details.
+| `['groups']?.contains('bbb2c5c5-a181-458a-a933-8ea7339d1310')`
+
+| `app.sso.configurations.<CONFIG>.username-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_USERNAME_CLAIM`
+| SpEL expression to override the default field for the username in the token claims.
+| `['unique_name']`
+
+| `app.sso.configurations.<CONFIG>.email-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_EMAIL_CLAIM`
+| SpEL expression to override the default field for the email in the token claims.
+| `['verified_email']`
+
+| `app.sso.configurations.<CONFIG>.firstname-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_FIRSTNAME_CLAIM`
+| SpEL expression to override the default field for the first name in the token claims.
+| `['given_name']`
+
+| `app.sso.configurations.<CONFIG>.lastname-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_LASTNAME_CLAIM`
+| SpEL expression to override the default field for the last name in the token claims.
+| `['family_name']`
+
+| `app.sso.configurations.<CONFIG>.client-id`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_CLIENT_ID`
+| Client ID of the Entra ID application.
+| `ccc0e55f-5f3e-4da8-9002-2830225aae1b`
+
+| `app.sso.configurations.<CONFIG>.scopes`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_SCOPES`
+| Comma-separated list of scopes to request during authentication.
+The scope should contain the "Application ID URI" followed by the scope name created in the previous step.
+| `api://ccc0e55f-5f3e-4da8-9002-2830225aae1b/nomserver`
+
+| `app.sso.configurations.<CONFIG>.authority`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_AUTHORITY`
+| Authority URL of the Entra ID tenant.
+It can be found in the "Endpoints" section of the application page.
+| `\https://login.microsoftonline.com/ddd85725-ed2a-49a4-a19e-11c8d29f9a0f`
+
+| `app.sso.configurations.<CONFIG>.issuer`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_ISSUER`
+| Issuer URL for validating the access token.
+It is usually derived from "Directory (tenant) ID" of the Entra ID app.
+| `\https://sts.windows.net/ddd85725-ed2a-49a4-a19e-11c8d29f9a0f/` (v1.0 tokens) or `\https://login.microsoftonline.com/ddd85725-ed2a-49a4-a19e-11c8d29f9a0f/v2.0` (v2.0 tokens)
+
+| `app.sso.configurations.<CONFIG>.audience`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_AUDIENCE`
+| Audience for validating the access token.
+It is usually the same as the "Application ID URI" shown on the "Expose an API" page in Entra ID. (optional)
+| `api://ccc0e55f-5f3e-4da8-9002-2830225aae1b` (v1.0 tokens) or `ccc0e55f-5f3e-4da8-9002-2830225aae1b` (v2.0 tokens)
+
 |===
 
 == Accessing Ops Manager

modules/ROOT/pages/installation/sso/configuration.adoc

@@ -0,0 +1,186 @@
+= Configuration
+:description: This section describes the configuration steps to enable Single Sign-On (SSO) for NOM server
+
+== Overview
+
+NOM supports SSO for authentication using external Identity Providers (IdP) that support OAuth2/OIDC implicit authentication flow.
+Currently, Microsoft Entra ID (formerly Azure Active Directory), Google Identity and Okta are supported.
+More IdP types and alternative authentication flows may be added in future NOM releases.
+SSO can be used as the only authentication method or in combination with username/password login.
+When both methods are enabled, users can choose the login method on the NOM login page.
+
+== Configuration
+
+One or more SSO configs can be set up containing the options needed to perform SSO authentication with an external Identity Provider (IdP).
+
+Configurations are identified by a name, which is used to reference the configuration in the environment variable names or command line arguments.
+The name can be freely chosen, but must consist only of alphanumeric characters.
+
+The configuration contains options needed to obtain, validate and map access tokens to SSO users in NOM, including assigning NOM roles to SSO users.
+
+Only the options needed for obtaining the token are sent to the frontend.
+
+Configurations are validated during the startup of NOM server.
+If a configuration is invalid, the errors are reported in the logs.
+
+=== Common options
+
+[cols="<,<,<, <",options="header"]
+|===
+| Command line argument
+| Environment variable name
+| Description
+| Example value
+
+| `app.sso.active-configurations`
+| `APP_SSO_ACTIVE_CONFIGURATIONS`
+| Lists comma-separated names of configurations that should be offered as login options on the NOM login page.
+| `myConfig1,myconfig2`
+
+| `app.username-password-login.enabled`
+| `APP_USERNAME_PASSWORD_LOGIN_ENABLED`
+| Username/password login can be enabled or disabled, enabling SSO login either be offered additionally or to be the only login method.
+If disabled, the pages "NOM Administrators" and "Profile" will not be available in the NOM UI.
+| `false`
+|===
+
+In the reference below, the placeholder `<CONFIG>` is used to indicate where the configuration name should be used (e.g. "myConfig1").
+
+
+[cols="<,<,<, <",options="header"]
+|===
+| Command line argument
+| Environment variable name
+| Description
+| Example value
+
+| `app.sso.configurations.<CONFIG>.idp-type`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_IDP_TYPE`
+| Type of the Identity Provider (IdP). Currently `ENTRA_ID`, `GOOGLE_IDENTITY` and `OKTA` are supported.
+| `ENTRA_ID`
+
+| `app.sso.configurations.<CONFIG>.grant-type`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_GRANT_TYPE`
+| Type of the OAuth authorization grant or flow to use. Currently `IMPLICIT`, `AUTHORIZATION_CODE` and `PKCE` are supported.
+| `IMPLICIT`
+
+| `app.sso.configurations.<CONFIG>.display-name`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_DISPLAY_NAME`
+| Display name of the login option on the NOM login page.
+| `Login with Entra ID`
+
+| `app.sso.configurations.<CONFIG>.admin-check`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_ADMIN_CHECK`
+| SpEL expression to check if the user should be assigned the NOM ADMIN role in NOM.
+See xref:_role_assignment[Role assignment] for details.
+| `['groups']?.contains('aaa63d30-70c3-4181-8c19-1b58e613f55b')`
+
+| `app.sso.configurations.<CONFIG>.read-only-user-check`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_READ_ONLY_USER_CHECK`
+| SpEL expression to check if the user should be assigned the NOM READ_ONLY_USER role in NOM.
+See xref:_role_assignment[Role assignment] for details.
+| `['groups']?.contains('bbb2c5c5-a181-458a-a933-8ea7339d1310')`
+
+| `app.sso.configurations.<CONFIG>.username-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_USERNAME_CLAIM`
+| SpEL expression to override the default field for the username in the token claims.
+| `['unique_name']`
+
+| `app.sso.configurations.<CONFIG>.email-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_EMAIL_CLAIM`
+| SpEL expression to override the default field for the email in the token claims.
+| `['verified_email']`
+
+| `app.sso.configurations.<CONFIG>.firstname-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_FIRSTNAME_CLAIM`
+| SpEL expression to override the default field for the first name in the token claims.
+| `['given_name']`
+
+| `app.sso.configurations.<CONFIG>.lastname-claim`
+| `APP_SSO_CONFIGURATIONS_<CONFIG>_LASTNAME_CLAIM`
+| SpEL expression to override the default field for the last name in the token claims.
+| `['family_name']`
+|===
+
+[#_role_assignment]
+==== Role assignment
+
+The `admin-check` and `read-only-user-check` options are https://docs.spring.io/spring-framework/reference/core/expressions/language-ref.html[SpEL expressions] that are evaluated against the claims in the access token obtained from the IdP.
+
+The claims object is available as the root object in the expression context.
+
+The expressions should evaluate to `true` or `false`.
+If the `admin-check` expression evaluates to `true`, the user is assigned the xref:../nom-user-management/index.adoc#_roles_of_nom_users[NOM Admin role].
+Otherwise, the read-only-user-check expression is evaluated.
+If it evaluates to `true`, the user is assigned the xref:../nom-user-management/index.adoc#_roles_of_nom_users[read-only Administrator] role.
+If both expressions evaluate to `false`, the user is denied access to NOM.
+
+*Examples of expressions*
+
+|===
+| Goal |Expression
+
+|Check that a list contains _all_ required values
+|`['groups']?.containsAll({'nom_group1', 'nom_group2'})`
+
+|Check that a list contains _at least one_ of the required values (with a logical expression)
+|`['groups']?.contains('nom_group1') or ['groups']?.contains('nom_group2')`
+
+|Check that a list contains _at least one_ of the required values (with a SpEL predicate expression)
+|`['groups'].?[ {'nom_group1', 'nom_group2'}.contains(#this) ].size() > 0`
+
+|===
+
+
+To debug issues with role assignment, see the xref:_troubleshooting[Troubleshooting section] below.
+
+==== Overriding claim fields
+
+By default, IdP specific fields in the token claims are used to create or update the SSO user fields in NOM.
+It is possible to override the default fields by providing SpEL expressions using the options `username-claim`, `email-claim`, `firstname-claim` and `lastname-claim`.
+
+The expressions should evaluate to a string value and are evaluated against the claims object in the access token.
+If an expression evaluates to `null` or if there are errors during evaluation, the corresponding user field is set according to the default behavior.
+
+For example, to use the JWT claim `verified_email` as user email address, use the config option `app.sso.configurations.<CONFIG>.email-claim=['verified_email']`.
+This expression evaluates to the value of the key `verified_email` in the JWT claims `Map`.
+
+Debugging issues with claim field extraction can be done as described in the xref:_troubleshooting[Troubleshooting section] below.
+
+[#_troubleshooting]
+== Troubleshooting
+
+=== General tips
+
+* Test in a private/incognito browser window to avoid issues with cached tokens or cookies.
+* Check the NOM server logs for errors during startup or user login (lines containing "SecurityLogger").
+* Verify that the callback URL configured in the IdP matches the one used in NOM server.
+* Ensure that the system time on the NOM server host is synchronized with a time server, as time discrepancies can cause token validation to fail.
+* Ensure that the NOM server can reach the IdP endpoints (authority, token, userinfo) over the network.
+
+=== Start with a simple configuration
+
+Set `admin-check` and `read-only-user-check` to `true` to verify that SSO authentication works in principle.
+If this does not work, check the configuration options for typos and verify that the callback URL configured in the IdP matches the one used in NOM server.
+
+=== Debugging role assignment and custom claim issues
+
+Enable debug logging by setting the NOM server config option `xref:../installation/server.adoc#config_ref[logging.level.com.neo4j.opsmanager.server.config]` to `debug`.
+With this setting, the evaluated role assignment expressions and the claims object are logged during user login, starting with a log line containing `SsoConfig tracing expression`.
+Example:
+
+[source,log]
+----
+2025-10-16T12:26:45.602+02:00 DEBUG 191053 --- [or-http-epoll-4] c.n.opsmanager.server.config.SsoConfigs  :
+SsoConfig tracing expression ['groups']?.contains('xb5c63d30-70c3-4181-8c19-1b58e613f55b') && ['groups']?.contains('aaa63d30-a181-458a-a933-8ea7339d1310')
+on the claims object
+{
+  sub=...,
+  ...
+  groups=[aaa63d30-a181-458a-a933-8ea7339d1310, ..., ...],
+  ...
+}
+2025-10-16T12:26:45.607+02:00 DEBUG 191053 --- [or-http-epoll-4] c.n.opsmanager.server.config.SsoConfigs  :
+Method call: [aaa63d30-a181-458a-a933-8ea7339d1310, ..., ...]}.contains}([aaa63d30-a181-458a-a933-8ea7339d1310]}) -> true}
+...
+----