Single Sign-On / External IdP

Ngenea Hub supports Hub login authentication via centralised single sign-on (SSO) in addition to local Hub authentication.

Hub login authentication is separate to the underlying PixStor operating system identity management.

Important

  • Single Sign On setup is a mandatory prerequisite for use of the Iris product feature

  • When Single Sign On is enabled, direct LDAP authentication cannot be used

  • Single Sign On can additionally provide federated LDAP authentication to an external Identity Provider (IdP)

  • Microsoft Active Directory is the only supported external Identity Provider

  • Single Sign On is orchestrated by PixStor and is not compatible with Ngenea Hubs deployed on non-PixStor platforms

Configuration

  • The following settings control Single Sign On setup and configuration for the Federated Identity Provider

  • The following are set in the main configuration file for Ngenea Hub at /etc/sysconfig/ngeneahub. Any setting which doesn’t specify a default is required when LDAP_ENABLED is true.

Note

Some configuration values are managed by PixStor’s configuration management. These can be observed with pixstor config get ngeneahub:sysconfig

Addtional settings can be managed via pixstor config set ngeneahub:sysconfig:<KEYNAME> <value>.E.G. pixstor config set ngeneahub:sysconfig:KEYCLOAK_ENABLED True

Refer to Feature Deployment/Hub 2 in the PixStor Deployment and Configuration Guide for further guidance on the full procedure of configuration management.

Warning

If both LDAP_ENABLED and KEYCLOAK_ENABLED are set to true, Hub will report an error and fail to start.

After changing settings in /etc/sysconfig/ngeneahub a Hub restart is required to reflect the changes applied.

Setting

Description

KEYCLOAK_ENABLED

Default: Set to True to enable SSO. Default: False. Not compatible with LDAP_ENABLED=True.

KEYCLOAK_BACKEND_CLIENT_ID

Default: ngeneahub-backend-client. SSO client for the ngeneahub_backend container. Modification of this parameter is not supported.

KEYCLOAK_CALLBACK_BASE_URL

Default: https://<myhubnodename>.pixstor

KEYCLOAK_FRONTEND_CLIENT_ID

Default: ngeneahub-frontend-client. SSO client for the ngeneahub_frontend container. Modification of this parameter is not supported.

KEYCLOAK_HTTPS_VERIFY

Default: /etc/ngenea/certs/ca-bundle.pem. [True|False]. Trusted SSL cert bundle for Hub’s internal backend SSO operations. Managed by Pixstor. True: Used where an externally SSL providers (versign, digikey, letsencrypt)- file not needed False: Do not verify provided SSL certs. This is insecure and not recommended in a production environment.

KEYCLOAK_LDAP_BIND_DN

Example: cn=mybinduser,cn=Users,dc=hubusers,dc=example,dc=com

KEYCLOAK_LDAP_GROUPS_DN

Example: cn=Groups,dc=hubgroup,dc=example,dc=com

KEYCLOAK_LDAP_NAME

Default: Active Directory

KEYCLOAK_LDAP_URL

Example: ldaps://ldap.example.com:636

KEYCLOAK_LDAP_USERS_DN

Example: cn=Users,dc=hubusers,dc=example,dc=com Default: “”

KEYCLOAK_MIRROR_GROUPS

Mirror Keycloak AD groups to HUB - When set to true, enables automatic import of group memberships from Active Directory. Where are present in Active Directory but not in Hub, groups are created. Changes to group membership in Hub do not effect changes in Active Directory. Default: False

KEYCLOAK_MIRROR_GROUPS_EXCEPT

Example: Administrators,Users,MyIdPGroup1,MyIdPGroup2 On user login, where KEYCLOAK_MIRROR_GROUPS=True, Hub groups are automatically created mirroring the Identity Provider (E.G. LDAP/Active Directory) group membership of the logged in user. Where the user is a member of a Hub group but not a member of the same named LDAP/Active Directory group, the user will be removed from the local Hub group - unless the group is defined in KEYCLOAK_MIRROR_GROUPS_EXCEPT. Excluding or replacing default groups such as Administrators,Users can lead to permission issues within the Hub, as these groups are used for access control. When removing the groups Administrators or Users from KEYCLOAK_MIRROR_GROUPS_EXCEPT, proceed with caution. Default: Administrators,Users.

KEYCLOAK_POST_LOGOUT_URI

Default: login Hub landing after SSO logout. Modification of this parameter is not supported.

KEYCLOAK_REALM

Default: iris SSO realm. Modification of this parameter is not supported.

KEYCLOAK_REDIRECT_URI

Default: /auth/callback Callback handles requests for OIDC compliant token exchange. Modification of this parameter is not supported.

KEYCLOAK_URL

Default: /keycloak/ Path to the SSO provider. Modification of this parameter is not supported.

Example Configurations and Setup

Note

Some configuration values are managed by PixStor’s configuration management. These can be observed with pixstor config get ngeneahub:sysconfig

Addtional settings can be managed via pixstor config set ngeneahub:sysconfig:<KEYNAME> <value>.E.G. pixstor config set ngeneahub:sysconfig:KEYCLOAK_ENABLED True

Refer to Feature Deployment/Hub 2 in the PixStor Deployment and Configuration Guide for further guidance on the full procedure of configuration management.

Standalone

In standalone mode, SSO is established between Ngenea Hub and Iris without the involvement of an external IdP (Microsoft Active Directory).

Prerequisites

  • A PixStor platform

  • Ngenea Hub

Standalone Single Sign On (no external IdP)

LDAP_ENABLED=False
KEYCLOAK_ENABLED=True
KEYCLOAK_BACKEND_CLIENT_ID=ngeneahub-backend-client
KEYCLOAK_CALLBACK_BASE_URL=https://myhubnodename.pixstor
KEYCLOAK_FRONTEND_CLIENT_ID=ngeneahub-frontend-client
KEYCLOAK_HTTPS_VERIFY=/etc/ngenea/certs/ca-bundle.pem
KEYCLOAK_POST_LOGOUT_URI=login
KEYCLOAK_REALM=iris
KEYCLOAK_REDIRECT_URI=/auth/callback
KEYCLOAK_URL=/keycloak/

External IdP

Prerequisites

  • A PixStor platform

  • Ngenea Hub

  • The Hub Site hosting Ngenea Hub must have been successfully joined to Active Directory through the Identity Management settings via the Ngenea Hub UI.

SSO with LDAP External IdP

Microsoft Active Directory is the only supported external IdP.

LDAP_ENABLED=False
KEYCLOAK_ENABLED=True
KEYCLOAK_BACKEND_CLIENT_ID=ngeneahub-backend-client
KEYCLOAK_CALLBACK_BASE_URL=https://myhubnodename.pixstor
KEYCLOAK_FRONTEND_CLIENT_ID=ngeneahub-frontend-client
KEYCLOAK_HTTPS_VERIFY=/etc/ngenea/certs/ca-bundle.pem
KEYCLOAK_LDAP_BIND_DN=CN=mybinduser,CN=Users,DC=example,DC=com
KEYCLOAK_LDAP_GROUPS_DN=CN=Users,DC=hubusers,DC=example,DC=com
KEYCLOAK_LDAP_NAME=Active Directory
KEYCLOAK_LDAP_URL=ldap://ldap.example.com:389
KEYCLOAK_LDAP_USERS_DN=CN=Users,DC=example,DC=com
KEYCLOAK_POST_LOGOUT_URI=login
KEYCLOAK_REALM=iris
KEYCLOAK_REDIRECT_URI=/auth/callback
KEYCLOAK_URL=/keycloak/

SSO with LDAPS External IdP

Microsoft Active Directory is the only supported external IdP.

LDAP_ENABLED=False
KEYCLOAK_ENABLED=True
KEYCLOAK_BACKEND_CLIENT_ID=ngeneahub-backend-client
KEYCLOAK_CALLBACK_BASE_URL=https://myhubnodename.pixstor
KEYCLOAK_FRONTEND_CLIENT_ID=ngeneahub-frontend-client
KEYCLOAK_HTTPS_VERIFY=/etc/ngenea/certs/ca-bundle.pem
KEYCLOAK_LDAP_BIND_DN=CN=mybinduser,CN=Users,DC=example,DC=com
KEYCLOAK_LDAP_GROUPS_DN=CN=Users,DC=hubusers,DC=example,DC=com
KEYCLOAK_LDAP_NAME=Active Directory
KEYCLOAK_LDAP_URL=ldaps://ldap.example.com:636
KEYCLOAK_LDAP_USERS_DN=CN=Users,DC=example,DC=com
KEYCLOAK_POST_LOGOUT_URI=login
KEYCLOAK_REALM=iris
KEYCLOAK_REDIRECT_URI=/auth/callback
KEYCLOAK_URL=/keycloak/

SSO with LDAP+STARTTLS External IdP

Microsoft Active Directory is the only supported external IdP.

LDAP_ENABLED=False
KEYCLOAK_ENABLED=True
KEYCLOAK_BACKEND_CLIENT_ID=ngeneahub-backend-client
KEYCLOAK_CALLBACK_BASE_URL=https://myhubnodename.pixstor
KEYCLOAK_FRONTEND_CLIENT_ID=ngeneahub-frontend-client
KEYCLOAK_HTTPS_VERIFY=/etc/ngenea/certs/ca-bundle.pem
KEYCLOAK_LDAP_BIND_DN=CN=mybinduser,CN=Users,DC=example,DC=com
KEYCLOAK_LDAP_GROUPS_DN=CN=Users,DC=hubusers,DC=example,DC=com
KEYCLOAK_LDAP_NAME=Active Directory
KEYCLOAK_LDAP_URL=ldap://ldap.example.com:389
KEYCLOAK_LDAP_USERS_DN=CN=Users,DC=hubusers,DC=example,DC=com
KEYCLOAK_POST_LOGOUT_URI=login
KEYCLOAK_REALM=iris
KEYCLOAK_REDIRECT_URI=/auth/callback
KEYCLOAK_URL=/keycloak/

Post configure and restart

Obtain the ngeneahub SSO master password:

root@myhubnode: # salt-call pixpillar.get_obfuscated keycloak:users:ngeneahub_master:password
local:
    THEPASSWORDISPRINTEDHERE

Follow the process relevant to the type of SSO setup configured in the /etc/sysconfig/ngeneahub configuration file.

Standalone SSO

root@myhubnode: # ngeneahubctl manage setup_keycloak --admin-user ngeneanhub_admin
Enter Keycloak admin password:              [Enter the ngeneahub_master password]
Authenticated with Keycloak
Updated client: ngeneahub-backend-client
'manage-users' already assigned to ngeneahub-backend-client, skipping.
Updated client: ngeneahub-frontend-client
Group mapper created successfully.
Keycloak clients configured successfully.

SSO LDAP/LDAPS with External Idp

root@myhubnode: # ngeneahubctl manage setup_keycloak --admin-user ngeneahub_master --setup-ad
Enter Keycloak admin password:             [Enter the ngeneahub_master password]
Enter Keycloak ldap bind credential:       [Enter the password of the user specified in KEYCLOAK_LDAP_BIND_DN]
Authenticated with Keycloak
Updated client: ngeneahub-backend-client
'manage-users' already assigned to ngeneahub-backend-client, skipping.
'view-realm' already assigned to ngeneahub-backend-client, skipping.
Updated client: ngeneahub-frontend-client
Group mapper already exists, skipping.
Updated existing Active Directory provider ZYLN_B8AQQeSFaC5CjCmDQ
LDAP test testConnection successful
LDAP test testAuthentication successful
Updated mapper 'creation date'
Updated mapper 'first name'
Updated mapper 'last name'
Updated mapper 'modify date'
Updated mapper 'email'
Updated mapper 'username'
Updated mapper 'group'
Synced LDAP groups for mapper '3fd3c16a-bfe4-47e6-a0c6-19befc2c7494'
LDAP user federation and mappers configured successfully
Keycloak clients configured successfully.

SSO LDAP+STARTTLS with External Idp

root@myhubnode: # ngeneahubctl manage setup_keycloak --admin-user ngeneahub_master --setup-ad --starttls
Enter Keycloak admin password:             [Enter the ngeneahub_master password]
Enter Keycloak ldap bind credential:       [Enter the password of the user specified in KEYCLOAK_LDAP_BIND_DN]
Authenticated with Keycloak
Updated client: ngeneahub-backend-client
'manage-users' already assigned to ngeneahub-backend-client, skipping.
'view-realm' already assigned to ngeneahub-backend-client, skipping.
Updated client: ngeneahub-frontend-client
Group mapper already exists, skipping.
Updated existing Active Directory provider ZYLN_B8AQQeSFaC5CjCmDQ
LDAP test testConnection successful
LDAP test testAuthentication successful
Updated mapper 'creation date'
Updated mapper 'first name'
Updated mapper 'last name'
Updated mapper 'modify date'
Updated mapper 'email'
Updated mapper 'username'
Updated mapper 'group'
Synced LDAP groups for mapper '3fd3c16a-bfe4-47e6-a0c6-19befc2c7494'
LDAP user federation and mappers configured successfully
Keycloak clients configured successfully.

Login

After following the relevant procedure and successful configuration users are able to login to Hub (and optionally Iris) with SSO via the Hub screen button Login with Iris at https://myhub/hub

Where user accounts are pre-existing before Single Sign On authentication is enabled, the user account must login to Hub using the alternative login method accessed through the or drop down on Hub’s login page. Upon successful login the user account is automatically synchronised to the Hub SSO provision which can then be accessed via the Login with Iris method.

On a user’s first successful Hub login using username/password, the Hub automatically creates the corresponding user and group records in the Hub SSO provision. Subsequent Hub user/group updates and deletions in the Hub are synchronised to Hub’s SSO provision. No changes in Hub are synchronised to the external IdP. The user can then be assigned to Hub groups by Hub Administrators to grant the user permissions within Hub. By default the created user has very limited access.