Okta on Linux

Prepare Okta

1. Create an API token in the Admin Console (under Security, API) for a super administrator. Set the org URL, then let the setup script prompt for the API token in the terminal. The prompt does not echo the token, and typing it there keeps it out of shell history:

   export OKTA_ORG_URL=https://example.okta.com

2. Turn on the LDAP Interface: Admin Console, Directory, Directory Integrations, Add LDAP Interface. Okta has no API for this step. It then serves ldaps://<org>.ldap.okta.com:636, with users under ou=users,dc=<org>,dc=okta,dc=com and groups under ou=groups,dc=<org>,dc=okta,dc=com.

3. Create the people as usual. You need:

   • the Linux users, ordinary Okta users with passwords, collected in one Okta group (engineering below) so the setup script can find them;
   • a bind user that SSSD reads the directory with: an ordinary Okta user with its own password, not a Linux account, not in the Linux groups;
   • the groups that will choose profiles, for example contractors and ml-research.

4. Prepare the org with the setup script. Run it from the kit folder of a checkout or source archive of the DefenseClaw repository, on any machine that can reach your Okta org over HTTPS; it does not have to be the Linux host. A command that writes prints its plan and changes nothing until you add --apply, so run each one without it first.

   ./okta-ldap-setup.py posix-schema --apply
   ./okta-ldap-setup.py assign-posix --users-from engineering --primary-group linux-users \
       --group contractors --group ml-research --apply
   ./okta-ldap-setup.py bind-role --bind-login ldap-bind@example.com --apply
   ./okta-ldap-setup.py signon-policy --bind-login ldap-bind@example.com --group linux-users --apply
   ./okta-ldap-setup.py check --bind-login ldap-bind@example.com --group linux-users \
       --group contractors --group ml-research

   Command	What it changes in Okta
   posix-schema	Adds the user attributes uidNumber, gidNumber, homeDirectory, loginShell and a unique unixUsername, and the group attribute gidNumber. Okta profiles carry no POSIX data, and the LDAP Interface exposes these custom attributes under the same names.
   assign-posix	Gives each selected user a uidNumber (from 1710000), unixUsername (the login's local part, lower case), gidNumber, homeDirectory and loginShell, adds the users to the primary group, and gives that group and each --group a gidNumber (from 1720000). SSSD skips a group without a gidNumber, such as Okta's built-in Everyone.
   bind-role	Creates a custom admin role with only okta.users.read and okta.groups.read, on a resource set of all users and groups, and assigns it to the bind user. Without a role the bind user sees only itself.
   signon-policy	Creates a sign-on policy for the LDAP Interface app with two password-only rules (one for the bind user, one for the group) and assigns it to the app. Its catch-all rule still requires a second factor from everyone else.
   check	Changes nothing. Reports what is ready and what is missing.

   assign-posix --home-template '/srv/home/{name}' --shell /bin/bash sets nondefault homes and shells. For homes outside /home and /var/home, add the parent to enterprise.enrollment.home_roots before enrollment. Accounts with /sbin/nologin, /usr/sbin/nologin or /bin/false shells are skipped by hook enrollment. verify-okta-identity.sh --user NAME reports the shell skip reason and points out nonstandard homes.

   Run assign-posix from one admin at a time. Okta does not enforce uniqueness on the numeric UID attribute in this schema; check detects duplicates, but concurrent assignments can otherwise pick the same number. If a UID is shared, clear it on one affected user's profile in Okta Admin Console (Directory > People > user > Profile), save, then rerun assign-posix --user LOGIN for that user. Every command can be run again and changes only what differs. Pick user and group IDs outside the local accounts of your hosts. The host step limits SSSD to the range 1710000 to 1729999 by default (--id-min and --id-max of install-sssd-okta.sh), which holds the IDs that assign-posix hands out by default.

In a test of the group rule, members of the group and the bind user could bind, and users outside the group were refused. Okta requires all the conditions of one rule to hold, so the script makes two rules instead of one rule naming both the bind user and the group.

Get an SSSD that can bind to Okta

SSSD 2.9, the version in RHEL 9, cannot bind to Okta. It always sends the password-policy request control, Okta answers with a response control that has no value, and SSSD 2.9 treats that as a failed bind. No Okta user resolves, getent passwd finds nothing, sssctl domain-status says Offline and the SSSD log says ldap_parse_passwordpolicy_control failed. Upstream SSSD 2.10.0 added the option ldap_use_ppolicy for this (SSSD commit 1980e2c4, issue 6666). Check your host:

grep ldap_use_ppolicy /usr/share/sssd/cfg_rules.ini    # a match means this SSSD can bind to Okta

To rebuild RHEL 9.8's SSSD with the option, run this as a normal user with sudo on a RHEL 9.8 host (about 15 minutes on 2 vCPUs). It installs rpm-build, gcc and SSSD build dependencies through sudo dnf (roughly 370 packages on a stock RHEL 9.8 host), then builds the SSSD packages. It does not install the rebuilt SSSD packages. Build on a separate host or container if the target must stay free of those dependencies; copy the RPMs from the printed RPMS directory to the target. Remove build-only dependencies on the build host only after recording which packages dnf added.

./build-sssd-ppolicy-backport.sh --workdir "$HOME/sssd-ppolicy-build"

The script is pinned to sssd-2.9.8-4.el9_8.1. The upstream patch does not apply to that tree, so backport-ppolicy.py makes the same change by exact text replacement and stops with the first text it does not find, so on any other SSSD release it fails instead of building something wrong. When it finishes, it prints the install commands: rpm -Uvh --oldpackage for the packages that are installed now (a local build has the dist tag .el9, which sorts below .el9_8.1), and an excludepkgs line for /etc/dnf/dnf.conf so that dnf upgrade cannot put the stock build back.

Configure the host

install-sssd-okta.sh configures SSSD, PAM and sshd on a RHEL-family host. It reads the bind password from a file (mode 0600), from OKTA_BIND_PASSWORD, or at a prompt, never from the command line. Read the password without echoing it so the dry run can test the bind as well; the command entered into shell history contains no password. Run as root, dry run first, then clear the variable:

read -rsp 'Okta bind password: ' OKTA_BIND_PASSWORD; printf '\n'
export OKTA_BIND_PASSWORD
sudo --preserve-env=OKTA_BIND_PASSWORD ./install-sssd-okta.sh --org example \
    --bind-login ldap-bind@example.com --allow-group linux-users --dry-run
sudo --preserve-env=OKTA_BIND_PASSWORD ./install-sssd-okta.sh --org example \
    --bind-login ldap-bind@example.com --allow-group linux-users
unset OKTA_BIND_PASSWORD

Choose an Okta group name absent from the host's /etc/group. The installer rejects a local name collision before changing the host because the sshd group rule would also permit password sign-in for members of that local group.

For Ansible, Puppet or another configuration manager, the final line is changed: 0 or changed: 1 on a successful apply. A dry run exits 0 when unchanged and 4 when it would change the host; it still checks the bind and can fail if the LDAP endpoint is unreachable. Run the dry run as root so it can compare the existing root-owned config. Treat exit 1, 2 and 3 as failures, not planned changes.

If you omit the bind password from --dry-run, the installer cannot compare the SSSD configuration. It skips the SSSD bind test and the config write and restart plan, and prints how to provide --bind-password-file or OKTA_BIND_PASSWORD for a complete plan. It still reports independent changes to packages, PAM, sshd, and SSSD boot enablement. An unchanged host can exit 0 in this mode without confirming that its SSSD configuration matches.

It:

1. refuses to go on when the host is not RHEL family, when a package is missing (--install-packages installs it), or when the installed SSSD has no ldap_use_ppolicy (exit 3 in each case, before any change);
2. renders sssd-okta.conf.tmpl with your values, checks it with sssctl config-check, and, when ldapsearch is installed (package openldap-clients), tests the bind user against Okta before it changes anything. A wrong password or a sign-on policy that refuses the bind user stops the run with exit 1 and leaves sssd.conf as it was;
3. installs /etc/sssd/sssd.conf (root, mode 0600), keeping the previous file as sssd.conf.bak-<time>. It will not replace an sssd.conf that it did not write unless you pass --force. A rerun also refuses to replace a marked file that contains another SSSD domain (for example, one added by an Active Directory join). Merge the updated Okta settings into that file manually, or pass --force if replacing every domain is intentional;
4. selects the authselect sssd profile with home directories (with-mkhomedir) and enables oddjobd;
5. writes /etc/ssh/sshd_config.d/45-okta-ldap.conf, so members of the allowed group can sign in with their Okta password and everyone else keeps the sshd default;
6. restarts SSSD when the config changed and waits for the okta domain to be Online.

A second run with the same options reports every step as unchanged. On another distribution, --render-only FILE writes the SSSD config to a file and checks it, and you install it yourself.

The template is the SSSD config that was run against Okta. The settings that are specific to Okta:

The names are bare (alice, ml-research) unless you set use_fully_qualified_names.

Check the accounts

verify-okta-identity.sh only reads. Run it as root on the host for every check, or as a normal user for the account checks:

sudo ./verify-okta-identity.sh --user alice --expect-group ml-research --allow-group linux-users

SSSD
PASS  sssd service is active
PASS  this SSSD knows ldap_use_ppolicy (it can bind to Okta)
PASS  the allowed group linux-users resolves
PASS  SSSD domain okta is Online
PASS  /etc/sssd/sssd.conf is root:root 0600
User alice
PASS  getent passwd: uid 1710001, gid 1720000, home /home/alice
      groups: linux-users ml-research
PASS  id -Gn lists ml-research

By hand, the same checks are getent passwd alice, id alice, sudo sssctl domain-status okta -o and an SSH sign-in with the Okta password. The sign-in works through sshd, PAM and pam_sss, which binds to Okta as the user; a wrong password is refused.

Install DefenseClaw and deliver the profiles

Install DefenseClaw for the Okta users as you would for any Linux user: a per-user install for each user, or the standalone enterprise package. Then give it profiles that name the complete Okta groups as id -Gn prints them. Matching ignores case, including in verify-okta-identity.sh --expect-group, so avoid groups whose names differ only by case:

• Standalone enterprise profile. Start from admin-config.example.yaml: it sets three profiles, assigns two of them to the groups contractors and ml-research, and makes okta-standard (block at HIGH) the default for everyone else. Change the group names, then apply it as root. ensure validates the file first and keeps the installed config when it is invalid, for example with unknown profile "okta-nope".

  sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ensure \
      --config /root/defenseclaw-config.yaml --json

• Per-user install. Merge the guardrail keys of user-config.example.yaml into the user's ~/.defenseclaw/config.yaml, then run defenseclaw config validate. The running gateway applies the change on its next reload.

Both examples use only built-in settings (mode, block_at), so they need no rule pack. The full set of profile keys, the precedence and the audit record are in User- and group-based policies.

Set a strict default_profile. A request whose user DefenseClaw cannot look up (for example while Okta and the SSSD cache are both unavailable) gets the default profile with the reason default_lookup_failed.

Confirm the profile

Ask DefenseClaw which profile each user gets:

sudo ./verify-okta-identity.sh --user alice --expect-profile okta-observe --connector claudecode
sudo ./verify-okta-identity.sh --user bob --expect-profile okta-strict --connector claudecode

On a managed host, run it as root: it calls defenseclaw-gateway enterprise linux profile-explain. On a per-user install, run it as the user whose gateway you want to ask: it calls defenseclaw guardrail profile explain. Those commands work on their own:

defenseclaw guardrail profile explain --user alice --connector claudecode
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux profile-explain --user alice --connector claudecode

A match of group with the group name shows the assignment worked. default means no assignment matched. default_lookup_failed means DefenseClaw could not look the user up.