X-Road admin SSO with LDAP and role mapping guide

Why X-Road admin SSO with LDAP and role mapping needs planning before the first login

X-Road admin SSO is set up by routing Security Server admin authentication through PAM and SSSD to LDAP or Active Directory, with directory groups mapped to the five X-Road roles: Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer. For a security or platform team that currently keeps local admin accounts on each server, this can look like a configuration task. In practice, most of the work is decided before anyone signs in. PAM and SSSD sit underneath the admin UI, so a mistake in that layer shows up as a lockout or as an operator with the wrong privileges on a production server. The design needs a named owner and a test plan before any live host is changed.

Role mapping carries the most risk. Each role covers different duties, from security configuration and member registration to service administration, system administration and read-only observation. Before creating any directory group, list who performs which tasks today, then decide whether each group maps to exactly one role or whether some people need several. Confirm in the user guide for your version how the Security Server evaluates a user who belongs to more than one mapped group, and who is allowed to change those groups. Record the result as an access matrix so auditors and your own staff can trace each grant to a business need.

Local break-glass access must survive a directory outage. If LDAP or Active Directory is unreachable, or a directory change breaks a group mapping, every Security Server that depends on it can lock out its operators. Plan at least one local emergency path, keep its credentials under dual control, and test it on each server type before cutover. The X-Road security hardening guidelines recommend locking accounts for 15 minutes after 3 failed logins and using passwords of at least 16 characters. Ask how lockout counters behave when the directory responds slowly, because repeated retries can lock out legitimate administrators during an incident.

The directory must be reachable from every Security Server that will use it, including servers in separate network zones. The Security Server serves its admin UI on TCP 4000 from internal networks, so the path from that network to the directory, including its TLS certificate chain, has to be open and tested before go-live. Confirm the exact LDAP or LDAPS ports, the SSSD settings and the PAM configuration against the Security Server user guide for your version, and do not assume that a setup from another X-Road version applies. This section covers admin logins on the Central Server and Security Server only. Member-to-member message exchange runs over TCP 5500 and is a separate path that this work should leave unchanged. Verify that in your test plan.

Which components carry admin identity in X-Road

Admin identity in X-Road touches more than the login screen. The Security Server admin UI, the PAM authentication layer, the SSSD bridge to the directory, and the five administrative roles all have to agree before a directory group can safely grant access. The Central Server and Configuration Proxy also need an identity decision, even if the first integration covers only Security Servers.

Security Server admin UI

The Security Server admin UI, served on TCP 4000 from internal networks, is where administrators manage keys, certificates, services and member configuration. Each login to this interface is an admin identity that the directory integration must recognize and authorize. Confirm in the user guide for your chosen release (7.8.3, 7.7.4 or 7.6.5) which functions each role can reach, and test every role against the UI before cutover.

PAM as the authentication layer

The Security Server authenticates admin users through PAM, so the login path depends on how PAM modules are configured on the host. Changes here affect every admin login, including the local fallback account you need during an outage. Confirm the PAM configuration required for LDAP integration in the user guide for your release, and document the break-glass procedure before changing anything.

SSSD as the directory bridge

SSSD connects the host to LDAP or Active Directory and resolves users and group membership for PAM. It is the component that makes a directory group visible to the Security Server at all. Check the connection type, certificate trust, and how group membership is retrieved, because a silent lookup failure can look like a wrong password. Verify SSSD independently of X-Road with a test account first.

Five X-Road administrative roles

The Security Server defines five user roles: Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer. Role mapping means deciding which directory groups receive which role, and keeping that mapping narrow. Confirm the exact permissions of each role in the user guide for your release, and agree the group-to-role table with the security and operations owners before implementation.

Central Server admin access

The Central Server holds the global configuration and manages member registration, so admin identity there carries wider consequences than a single Security Server. Decide whether the same directory integration applies to Central Server administrators or whether they stay on a separate account model. Confirm how the Central Server authenticates admins for your chosen release, since the Security Server guidance does not settle this on its own.

Configuration Proxy in the admin path

The Configuration Proxy distributes configuration between X-Road components, so it sits in the path that admin changes travel through. Identity decisions made on the Security Server may not cover actions that reach it indirectly. Confirm with the user guide and your deployment architecture which admin actions touch the Configuration Proxy, and include those paths in your access review and test plan.

Which directory and mapping choices to settle before configuring SSO

This table compares the four decisions that shape an X-Road admin SSO design: the directory source, how roles are mapped, whether local break-glass accounts remain, and where SSSD caches credentials. Read each row for the conditions where an option fits and the operational work it creates after go-live. The main takeaway is that every mapping change or directory change must be tested on each Security Server, so decide these choices before configuration starts.

Decision	When it fits	Operational cost
LDAP versus Active Directory as source	LDAP fits where an existing directory already serves Linux hosts and group schemas are under your control. Active Directory fits where Windows-based identity governance already owns admin groups.	Confirm group object types, nesting behavior and attribute names with the directory team, because SSSD group lookups depend on them and differ between the two.
Role mapping by group membership	Fits most deployments, since the five X-Road admin roles map to a small number of directory groups that governance teams can review.	Requires ongoing group governance: owners, membership reviews and a change path for every group that maps to a role on each Security Server.
Role mapping by individual user	Fits only very small teams or temporary access where a named exception is needed and reviewed.	Each joiner, mover and leaver change must be made per user on every Security Server, which increases drift and review effort.
Local break-glass admin accounts	Fits environments that must keep administrative access when the directory or network path to it is unavailable.	Local credentials must be stored, rotated and tested under your own procedure, and they need monitoring so they are not used for routine work.
Full directory dependence	Fits organizations that require every admin login to pass through central identity controls with no local accounts.	Directory outages or misconfigured mappings can lock administrators out, so recovery steps must be documented and rehearsed.
Where SSSD caches credentials	Caching fits sites where Security Servers must remain reachable for admin logins during short directory outages.	Cached credentials and group data must be scoped, expired and reviewed against your policy, and a revoked user may still log in until the cache expires.

How to configure PAM, SSSD and group-to-role mapping step by step

This sequence connects X-Road Security Server admin logins to an LDAP or Active Directory directory through PAM and SSSD, with each directory group mapped to one administrative role. Each step ends with a check, so the team can confirm the login path works before the next change is made.

Confirm the operating system and X-Road release
The platform team confirms that each Security Server runs Ubuntu Server 22.04 or 24.04 LTS on x86-64, or Red Hat Enterprise Linux 8 or 9, and records the exact X-Road release in use. The current release is 7.8.3, and 7.7.4 and 7.6.5 are also supported. Confirm the directory product version and the TLS certificate chain with the directory team. The step is complete when the OS, X-Road version and directory details are written into the change record and match the supported combinations in the installation guide.
Create directory groups and test accounts
The directory team creates one group for each of the five X-Road administrative roles: Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer. They also create a small set of test accounts, with one account in each group and one account in no X-Road group. Keep the group names and membership rules in the change record. The step is complete when a directory lookup returns the expected group membership for every test account from a Security Server host.
Install and configure SSSD over TLS
The Security Server administrator installs SSSD and configures it against the LDAP or Active Directory endpoint, using TLS for every connection and a CA certificate that the server trusts. Restrict the search base to the groups and users that administrators need, and set a bind account with read-only rights. Confirm the exact configuration keys against the vendor documentation for the SSSD version in your OS. The step is complete when getent output shows the test users and their groups, and a connection attempt without a valid certificate fails.
Configure PAM for the X-Road admin login
The administrator adds the SSSD module to the PAM stack that the X-Road admin login uses, following the Security Server user guide. Keep the existing local authentication path in place until the directory path has been tested end to end. Make sure the SSH and console policies are changed only as intended, so a failed directory service does not lock every administrator out. The step is complete when a test account from an allowed group signs in to the admin UI, and a test account from outside the groups is denied.
Map each directory group to one role
The administrator maps each directory group to exactly one X-Road role using the group-to-role method described in the Security Server user guide. A user who belongs to several mapped groups should be reviewed, because the role outcome must be predictable. Record each mapping in a table with the group name, role and approver. The step is complete when a login from each test account lands in the expected role, and the account with no X-Road group cannot reach any admin function.
Keep and document a local break-glass account
The administrator keeps one local break-glass account that does not depend on SSSD or the directory, and stores its credentials in the organization's approved secrets store with a named custodian. Document when it may be used, who must approve its use, and how each use is logged and reviewed. Account lockout settings should be checked against the hardening guidance, which recommends locking accounts for 15 minutes after 3 failed logins. The step is complete when the break-glass login is tested in a maintenance window and the test is recorded.
Confirm the admin UI is internal only
The network team confirms that the admin UI on TCP 4000 is reachable only from the internal administration network, and that TCP 5500 and 5577 are open to external networks for message exchange and OCSP as the installation guide describes. Test the admin UI from an internal host and from an external host, and confirm that the external attempt fails. Review the host header and allowed hostname settings against the hardening guidance. The step is complete when the external connection to TCP 4000 is refused and the internal login succeeds.

What drives the effort and cost of directory-based X-Road admin access

This table lists the factors that change the work of connecting X-Road admin logins to LDAP or Active Directory, and how to keep each one under control. Read each row as a lever: the first column names the driver, the second explains why it moves effort, and the third gives the practices that hold it down. The main takeaway is that a standardized SSSD and group-mapping pattern, applied to a small number of roles, usually matters more than raw node count.

Driver	Why it changes effort or cost	How to keep it down
Number of Security Servers	Each node needs its own PAM and SSSD configuration, group mapping check and login test, so effort grows with every host added.	Build one SSSD and PAM template and apply it to every node through configuration management.
Number of Central Servers	Each Central Server adds another admin login surface and must be verified against the same role mapping.	Keep the directory mapping identical across Central and Security Servers and test once against a shared checklist.
Number of admins and role variants	More named people and more distinct role combinations increase group design, review and access testing.	Map a small set of directory groups to the five X-Road roles and avoid one-off group combinations per person.
Directory type and governance maturity	A well governed Active Directory or LDAP with clean group ownership needs less cleanup than one with nested or stale groups.	Confirm group ownership and naming before design starts, and ask the directory team to provide dedicated X-Road groups.
TLS and certificate handling to the directory	LDAPS or StartTLS requires trusted directory certificates on each node, and certificate renewal adds a recurring task.	Use one internal certificate authority chain for all nodes and confirm the renewal owner and process in writing.
Number of environments	Test, staging and production each need their own directory bindings, group mappings and verification runs.	Reuse a single test directory or lab realm for all pre-production environments and promote the same configuration files.
Depth of audit and evidence requirements	Assessors may ask for login logs, role change records and proof of periodic access reviews, which adds collection and documentation work.	Agree the evidence list early, centralize authentication logs and produce a reusable access review template.
Customization	Non-standard PAM stacks, additional identity providers or custom group logic move the work away from the documented pattern.	Limit changes to the documented PAM and SSSD approach and record every deviation in the design document.

How SSO changes across single servers, multi-node estates and air-gapped networks

A single Security Server with one directory is the simplest case. PAM authenticates admin users on the host, SSSD resolves the directory, and directory groups are mapped to the five X-Road roles: Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer. The design still needs to be settled before the mapping is written, because every later node will copy it.

Per node: the PAM and SSSD configuration, the group-to-role mapping and a test login for each role, since the host enforces its own login stack.
Consistent: the base DN, group names and the bind account SSSD uses, so that a group resolves to the same role on every login.
Confirm: whether the directory connection is encrypted, which accounts may administer the host itself, and whether a local break-glass account exists under your hardening controls.
Confirm: that role assignments follow your separation of duties, including that no single group carries both Security Officer and Registration Officer.

Before go-live, log in as one user per role and confirm each sees only the screens that role should have.

Securing the admin path once directory login is in place

Directory login moves the trust decision for X-Road admin access into LDAP or Active Directory, which makes the directory path itself a security boundary. The cards below cover the connection, the bind credentials, the admin UI exposure, the break-glass account and the role separation that together decide who can change a Central Server or Security Server. Lockout, SSH and password policy are covered in the hardening topic and are not repeated here.

Encrypting the directory connection

PAM and SSSD must reach the LDAP or AD server over an encrypted channel, so the directory traffic carrying admin logins and group lookups is not readable on the network. Confirm with your directory team which encryption method and certificate chain the domain controllers or LDAP servers support, and that the Security Server trusts the issuing CA. Test the connection from the Security Server itself, since a working login from another host proves nothing about this path.

Limiting which groups reach the admin UI

Directory login only controls who can authenticate, so the SSSD access rules and the PAM configuration must also restrict which groups may log in to the Security Server at all. A group that maps to an X-Road role but is not allowed to log in is a configuration error to fix before go-live. Review the allowed group list whenever a team changes, because stale membership is the most common way former staff keep access.

Protecting the bind account

The service account that SSSD uses to query the directory holds a credential stored on each Security Server, so it needs the narrowest read rights that group lookups require. Keep the password out of shared scripts and configuration files that other administrators can read, and plan a rotation procedure that updates every Security Server in the same change window. Ask the directory team whether the account can be restricted to specific organizational units.

Keeping the break-glass account offline

A local break-glass account lets the team recover the Security Server when the directory or SSSD fails, so it must exist and must work. Store its credentials in a sealed, access-logged location outside the directory, and test it on a schedule rather than during an incident. Record who may retrieve it and what triggers its use, and confirm that using it raises an alert.

Restricting admin UI exposure to internal networks

The admin UI listens on TCP 4000, which must be reachable only from internal administration networks and never from the external message exchange or OCSP interfaces. Check the firewall and any load balancer rules on each Security Server, and confirm that a host on the external network cannot reach that port. Repeat the check after every host move or network change, because a single permissive rule exposes the login page.

Separating roles across directory groups

The five X-Road roles, Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer, carry duties that should not sit with one person. Map each directory group to one role or to a set of roles that do not conflict, and document which combinations are forbidden. Review the mapping with the security owner before go-live, because a group that carries both approval and configuration rights defeats the separation.

How to test that directory login works and fails safely

Test the directory login before anyone relies on it, and test the failure paths as carefully as the success path. For X-Road admin SSO, the Security Server authenticates admin users through PAM, with SSSD connecting PAM to LDAP or Active Directory and LDAP groups mapped to the five X-Road roles: Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer. Each test below should be written down with the account used, the group membership, the expected role and the observed result before the integration goes live.

Role mapping tests. Pick one test account in each mapped group and log in to the admin UI. Confirm that the account sees the functions of its mapped role and nothing from the other four roles. Then try a few actions that belong to other roles, such as a Service Administrator attempting a registration task, and confirm they are refused. Also test a user who belongs to two mapped groups, because the outcome depends on how your SSSD and group configuration resolve overlapping memberships. Confirm that outcome with your own configuration rather than assuming it.

Refusal and disabled-account tests. A user who is outside every mapped group should be refused, even if the directory account itself is valid. Separately, disable a test account in the directory and attempt a login. Access should end at the next login attempt. Check whether existing sessions survive the change and record the session lifetime you have configured, since a disabled account can keep an open session until that session expires or is ended.

Directory outage and break-glass tests. Simulate a directory outage by blocking the Security Server's route to the LDAP or Active Directory servers in a test environment. The local break-glass account should still log in, and the failure should appear in the authentication and system logs with enough detail to diagnose it. Confirm that the break-glass credential is stored under your own controls, that its use triggers an alert or review, and that it is tested on a schedule. The hardening guide's account lockout guidance (15 minutes after 3 failed logins) applies to these accounts, so test that lockout behavior too.

Network exposure test. From an external network, confirm that the admin UI on TCP 4000 cannot be reached. The installation guide lists TCP 5500 and 5577 as the ports open to external networks, so a scan from outside should show no response on 4000. Repeat the scan after every firewall or cloud security group change. Record the scan tool, source address, date and result as evidence. Recording evidence. Store each test with its date, tester, environment, account, expected result, actual result and log excerpt. Keep the configuration files and group mappings as they existed during the test. DeployOpen can prepare this evidence package for an internal audit or compliance assessment. Independent auditors issue any assessment outcome, so ask them early which evidence format and sampling approach they expect.

What to monitor, back up, upgrade and document after SSO goes live

This table lists the recurring operational tasks for X-Road admin SSO, what each one covers and what evidence to keep. Read it as a runbook outline: each row names a task, what it protects and the record your team should be able to produce on request. The main takeaway is that the SSO setup remains a control only while monitoring, group reviews, backups and post-upgrade checks are kept current.

Area	What to do	What to keep as evidence
SSSD and directory connectivity	Monitor SSSD service status and its connection to the LDAP or Active Directory servers, and alert when admin logins cannot resolve group membership	Alert rules, sample alert history and the escalation contact for directory outages
Failed admin logins	Collect PAM authentication failures for Security Server and Central Server admin accounts and review them against the lockout threshold in the hardening guidance	Log retention settings, review records and any lockout events with the follow-up action
Directory group membership review	Review members of each X-Road role group on a fixed schedule and remove leavers, movers and accounts no longer needed	Signed review sign-off per group, dated, with the approver named and removals recorded
PAM and SSSD configuration backup	Back up the PAM and SSSD configuration files and the group-to-role mapping record, and store them with the host configuration	Dated backup copies, a restore test result and the change record for the last configuration edit
Break-glass account test	Test the local break-glass admin account that works when the directory is unavailable, confirm its credentials are held under dual control, and confirm it is disabled for daily use	Test date, result, who witnessed it and proof that the credential rotation followed the test
Re-validation after X-Road upgrades	After each upgrade on a supported release (7.8.3, 7.7.4 or 7.6.5), re-test SSO login and each role mapping on Central and Security Servers before returning to production	Upgrade test plan, per-role login results and the sign-off for the upgraded host
Group-to-role ownership	Record which directory group owns each of the five X-Road roles, the person accountable for it and the membership criteria	Current ownership register, reviewed at the same cadence as group membership
Change request process	Define how a team requests a new group, a role change or a mapping change, who approves it and how it is tested in a non-production host first	Request tickets, approvals, test results and the date each change went live
X-Road 8 planning	X-Road 8 is in beta, so treat any move to it as a new build that needs its own validation of this SSO setup, including PAM and role mapping	Validation plan and results for the SSO setup on the target release before cutover

Questions teams ask before configuring X-Road admin SSO

Can our internal team set up X-Road admin SSO without a partner?

Yes, if your team already runs Linux administration, PAM and SSSD, and has someone who understands your directory design. X-Road authenticates admin users through PAM, and PAM can use SSSD to query LDAP, so the core work is standard Linux identity configuration plus mapping directory groups to the five X-Road administrative roles. The risk is not the tooling but the change itself: a mistake in PAM or SSSD can lock every administrator out of a Security Server. Teams without a tested break-glass account, a staging environment or recent X-Road administration experience usually benefit from a second pair of hands on the first rollout. Ask your own team to confirm these skills before deciding.

What makes the cost of X-Road admin SSO go up or down?

Cost follows the labor needed to design, build, test and hand over the setup, plus any environment work it depends on. The main components are directory design (how many groups map to the five roles and how clean your existing groups are), the number of Security Servers and Central Servers that must be configured identically, the amount of test and staging work, and documentation and knowledge transfer for the operations team. Recurring costs are small by comparison and mostly come from directory changes and periodic access reviews. When you request a quote, ask for the written scope, the list of servers and environments covered, who performs testing and rollback planning, and what happens if a change window is missed.

How long does X-Road admin SSO take to configure?

Duration depends less on the X-Road settings than on how quickly your directory and change processes can answer questions. The work usually moves through directory review, group design, a lab build, testing with test accounts, and then a controlled production change. The number of servers, whether a staging environment exists, and how many approvals each change needs are the biggest drivers. Teams with clean LDAP or Active Directory groups and a standing change window move faster. Teams that must first clean up nested groups or agree on role ownership will spend most of their time there. Ask any provider for a timeline tied to your environment and the dependencies it lists, not a generic figure.

What does our team need to provide before the work starts?

The work needs four things from your side. First, read-only directory access, including a bind account and the base distinguished names for users and groups. Second, a group design decision: which directory groups map to which of the five X-Road roles (Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer), and who approves membership. Third, test accounts in a non-production directory or a dedicated test OU, with at least one account per role. Fourth, change windows on each Security Server, plus a named contact who can approve a rollback. Also confirm that you have a local break-glass administrator that does not depend on the directory.

Does LDAP differ from Active Directory for X-Road admin SSO?

The X-Road side of the design is the same: PAM authenticates the admin, SSSD handles the directory lookup, and LDAP groups map to X-Road roles. The differences sit in the directory and the SSSD configuration. Active Directory has its own schema conventions for users, groups and nested membership, and its group lookups and password policies are often managed by a different team than a generic LDAP server. Confirm with your directory team how nested groups are resolved, which attribute carries group membership, whether TLS is required for the connection, and how account lockout in the directory interacts with the lockout settings recommended in the X-Road hardening guidance. Test both paths in staging before choosing.

Will changing admin login affect message exchange between members?

Changing admin login should not change message exchange directly, because admin authentication controls the administrative user interface and configuration actions, not the message path. Message exchange runs on TCP 5500 from external networks, OCSP runs on 5577, and the admin UI runs on TCP 4000 from internal networks, so the admin change touches only the internal access path. The indirect risk is operational: a misconfigured PAM or SSSD setup could block an administrator who needs to renew certificates or fix a fault during an incident. For that reason, verify message exchange with a test service call after each change, and keep the break-glass path tested before any production change.

What does a fixed-scope DeployOpen engagement for this cover?

A fixed-scope engagement covers the agreed systems, deliverables and timeline, and it is confirmed in writing before work starts. For this topic, that typically means a review of your directory structure, a role mapping design, PAM and SSSD configuration for the agreed Security Servers and Central Servers, test verification with test accounts, rollback and break-glass procedures, and a handover document for your operations team. It does not include changes to your directory beyond the agreed scope, and it does not include audit reports or certifications, which independent auditors issue. Ongoing support, upgrades and periodic access reviews can be added as a retainer.

How DeployOpen scopes, builds and hands over X-Road admin SSO

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure. For X-Road admin SSO, that means linking Central Server and Security Server admin logins through PAM and SSSD to your LDAP or Active Directory directory, with directory groups mapped to the five X-Road administrative roles. Engagements are fixed-scope, with scope and deliverables agreed in writing before work starts.

How we scope

The written scope names each Central Server and Security Server that will use directory-backed admin login.
We confirm the directory type, LDAP or Active Directory, and which groups hold each of the five roles.
Scope lists the SSSD and PAM configuration, test accounts and the evidence each handover will include.

How we build

Configure PAM and SSSD on each host to authenticate admin users against the agreed LDAP or Active Directory domain.
Map directory groups to Security Officer, Registration Officer, Service Administrator, System Administrator and Security Server Observer.
Test each role with a dedicated account, including denied access for users outside the mapped groups.

How we hand over

Deliver a runbook covering the PAM, SSSD and group-to-role mapping settings for each host.
Document lockout and password settings aligned with NIIS hardening guidance, such as a 15-minute lock after 3 failed logins.
Walk the client's administrators through login, role checks and the rollback steps before the engagement closes.

How we support

Ongoing support is available as a retainer that can cover directory changes, new hosts and group-to-role updates.
Confirm PAM and SSSD changes against the X-Road documentation for your release before applying them.
Re-test role mappings after every X-Road upgrade, including moves between supported 7.x releases.

X-Road admin SSO with LDAP and role mapping