docs: add the connector documentation page and correct the README - #51
docs: add the connector documentation page and correct the README#51carolinaroncaglia wants to merge 2 commits into
Conversation
The connector shipped without any customer documentation: no docs/ directory, no published page, and the README pointed at a URL that returns 404. Add the public setup page and the internal scoping summary, and correct the README where it disagreed with the code. - docs/connector.mdx: capabilities table for all five resource types, how HBAC rules become host and host-group entitlements, the wildcard rule modelled as a virtual any-host/anyone resource, credential gathering, and the self-hosted configuration walkthrough. The connector runs against an on-premises directory, so the cloud-hosted tab records that a cloud-hosted connector is not currently available, matching the LDAP page. - docs/docs-info.md: resource and provisioning tables, the credentials and the directory permissions each one needs, and the read-only versus read-write split. - README.md: drop the logo reference and the documentation link, both of which resolve to nothing; document --role-search-dn, --filter, --insecure-skip-verify and --disable-operational-attrs; describe provisioning as it is implemented, including account deletion; and correct the data model, where HBAC rules were listed as a synced resource type rather than as the source of host entitlements. - scripts/local-ldap/README.md: the hosted-mode section described the pre-removal architecture, telling the reader to strip rs.WithExternalID calls that no longer exist and describing getDNFromResource as preferring the trait profile when it reads the resource profile exclusively. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| - Host and host-group access comes from your HBAC rules rather than from a fixed entitlement per resource. Each rule that names a host or host group becomes an entitlement on that resource, so what C1 shows follows the rules you have written. | ||
| - A rule that applies to every host or every user — one whose `hostCategory` or `userCategory` is set to `all`, such as the `allow_all` rule FreeIPA ships — appears in C1 as a grant against a single **Any host** or **Anyone** resource, rather than being expanded across your whole estate. | ||
| - Group and role memberships expand. When a group is granted a role, C1 resolves the group's members through to that role, including members reached through nested groups. | ||
| - The connector deletes user accounts when C1 deprovisions them. It does not create accounts. |
There was a problem hiding this comment.
🟡 Suggestion: Worth verifying this claim end-to-end before publishing. userResourceType.Delete (pkg/connector/user.go:351) does ldap.CanonicalizeDN(resourceId.Resource), but user resources are built with ipaUniqueID as the resource ID (pkg/connector/user.go:257), so ParseDN on a UUID should fail and the delete would error rather than remove the entry. If that is the case, this bullet and the Users … ✅ deletes the directory entry row in docs/docs-info.md:23 overstate what works today.
There was a problem hiding this comment.
Softened the doc claim instead of asserting deletion works — added AUTO-GENERATED markers, and reworded the Accounts bullet/table to note that Delete/Get currently mismatch the resource ID (ipaUniqueID vs DN), so deletion errors rather than works today. Not fixing the underlying Go bug in this docs-only PR.
|
|
||
| | Resource | Sync | Provision | | ||
| | :--- | :--- | :--- | | ||
| | Accounts | <Icon icon="square-check" iconType="solid" color="#c937ae"/> | | |
There was a problem hiding this comment.
🟡 Suggestion: The Accounts row leaves the Provision column empty, but baton_capabilities.json declares CAPABILITY_RESOURCE_DELETE on user, and both the note at line 27 and docs/docs-info.md say accounts are deprovisioned by deletion. The table and the prose disagree — either mark the row (with a "delete only, no create" qualifier) or say in the table why deletion is not counted as provisioning.
There was a problem hiding this comment.
Table already left the Provision cell blank for Accounts, and now the prose agrees (deletion currently errors rather than works, so it is not counted as a working Provision capability). Kept the empty cell rather than adding a checkmark.
| BATON_BASE_DN: <The distinguished name to search under> | ||
|
|
||
| # Optional: include if you want C1 to provision access using this connector | ||
| BATON_PROVISIONING: true |
There was a problem hiding this comment.
🟡 Suggestion: BATON_PROVISIONING: true parses as a YAML boolean, but Secret.stringData is map[string]string, so a copy-pasted manifest fails with cannot unmarshal bool into ... of type string. Same issue with the baton: true pod label at line 176 (labels are also string-valued). Quoting both ("true") makes the snippets apply cleanly — note the sibling connector pages carry the same unquoted pattern, so this may be a template-wide fix rather than a change for this PR alone.
There was a problem hiding this comment.
Quoted both — BATON_PROVISIONING: "true" here and baton: "true" at the pod-label line — so the manifests apply cleanly. Left the sibling connector pages alone since fixing the shared template is out of scope for this PR.
|
|
||
| - Users (`posixAccount`) | ||
| - Groups (`ipaUserGroup`) — entitlements: `member`, `manager` | ||
| - Roles (`groupOfNames` under the role search DN) — entitlement: `member`, grantable to users, groups, hosts and host groups |
There was a problem hiding this comment.
🟡 Suggestion: The role filter is (&(objectClass=groupofnames)(cn:dn:=roles)) (pkg/connector/role.go:22), so a role entry must also have a cn=roles component in its DN — the search DN alone is not sufficient. Pointing --role-search-dn at a container without cn=roles in the path silently syncs zero roles, which is worth stating here and in the --role-search-dn row above.
There was a problem hiding this comment.
Added the cn=roles DN requirement to this row and to the Data Model bullet in the README.
Connector PR Review: docs: add the connector documentation page and correct the READMEBlocking Issues: 0 | Suggestions: 1 | Threads Resolved: 0 Review SummaryDocumentation-only change ( Security IssuesNone found. Correctness IssuesNone found. Suggestions
Prompt for AI agents |
mateoHernandez123
left a comment
mateoHernandez123
left a comment
There was a problem hiding this comment.
Docs-only, verified against the connector at HEAD: frontmatter, resource set, credentials, the ECR image + Kubernetes shape, and the completion message all check out. Approving to unblock.
Two non-blocking things worth addressing (neither caught by the review bot):
-
The new connector.mdx is missing the AUTO-GENERATED markers — both around the capabilities table and for the Cloud-hosted config-params block. Adding them lets Generate Baton Metadata keep the capabilities table in sync and gives the CI metadata step the anchors it expects on a fresh mdx.
-
Heads-up on the account-deletion claim: I traced Delete() and it currently mishandles the user ID. User resources are keyed by the UUID (ipaUniqueID), but Delete parses that value as a DN (CanonicalizeDN) and ignores the profile "path", so it errors out instead of deleting (Get has the same mismatch, and there's no CreateAccount). I'd hold off documenting account deletion / adding a Provision checkmark for Accounts until that's fixed — otherwise the docs advertise a capability that doesn't work today. The code bug doesn't seem tracked anywhere yet, so it's probably worth its own ticket.
- Add AUTO-GENERATED markers around the capabilities table - Correct account-deletion claims: Delete/Get canonicalize the user resource ID as a DN, but user resources are keyed by ipaUniqueID, so deletion currently errors instead of removing the entry - Note the cn=roles DN requirement for --role-search-dn - Quote YAML boolean values in the Kubernetes manifest snippets - Rename "Any host" to "Any" to match the resource's display name in code Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
| - Host | ||
| - Host Groups | ||
| - HBAC Rules | ||
| HBAC rules (`ipaHBACRule`) are read but are not synced as a resource type of their own. They are the source of the entitlements that appear on hosts and host groups: each rule naming a host or host group becomes an entitlement on it. A rule whose `hostCategory` or `userCategory` is `all` — including the `allow_all` rule FreeIPA ships — is emitted against a single virtual `any-host` or `anyone` resource rather than expanded across every host. |
There was a problem hiding this comment.
🟡 Suggestion: The virtual wildcard group is anyone-group in code (pkg/connector/group.go:37), displayed as Anyone; anyone matches neither the ID nor the display name. The host one is correct (any-host, pkg/connector/host.go:22). Worth aligning so a reader searching C1 for these resources finds them.
3 participants
Summary
This connector shipped without any customer documentation. There is no
docs/directory in the repository, no page on the docs site, and the README's one documentation link returns 404. This adds the public setup page and the internal scoping summary, and corrects the README where it disagreed with the code.Because the connector repository is upstream of the docs site, the page is created here rather than in the docs repo.
What the audit found, and what changed
No documentation exists anywhere.
docs/is absent on bothmainand the latest tag. The docs site has no page for this connector. The LDAP page that a reader might land on instead documents three resource types with different object classes, and never mentions IPA, FreeIPA, 389 or HBAC — so it does not cover this connector by inclusion. Addeddocs/connector.mdxanddocs/docs-info.md.The README's documentation link is dead. It pointed at
conductorone.com/docs/product/integrations/ldap/, which 404s. Replaced with a relative link to the new page.Four supported flags were undocumented.
--role-search-dn,--filter,--insecure-skip-verifyand--disable-operational-attrs, all defined inpkg/config/config.go. The last one matters most: setting it silently removeslast_loginandcreated_atfrom every account, which the README did not say.Provisioning was described as groups and roles only, while
baton_capabilities.jsondeclaresCAPABILITY_RESOURCE_DELETEonuserand it is implemented atpkg/connector/user.go:351. The flag description now covers account deletion.The data model listed HBAC rules as a synced resource type. They are read but not synced as a resource type — they are the source of the entitlements that appear on hosts and host groups. Corrected, including the wildcard rule that is emitted against a virtual
any-host/anyoneresource rather than expanded across the estate.Two README elements resolved to nothing: a logo reference into a
docs/images/tree that does not exist, and an empty## LDAPheading. Both removed. The logo line is inherited from sibling connectors where it is equally broken; removing it matches whatbaton-datadogdoes.scripts/local-ldap/README.mddescribed the pre-removal architecture. Its hosted-mode section told the reader to deleters.WithExternalID(...)options that no longer exist in this repo, and describedgetDNFromResource()as preferring the trait profile when it reads the resource profile exclusively. Rewritten, and it now names the one thing a local run still cannot reach: the write path as hosted mode sees it, because the SDK's local provisioner rebuilds the principal without its profile.Notes for review
docs/connector.mdx. The in-repo template's naming line saysdocs.mdx, but every sibling connector repo checked usesdocs/connector.mdx, and the template defers to the convention already established.AUTO-GENERATEDmarkers. No generator is wired for the capabilities table in this family, and the sibling pages carry none.Metadata()saysIPA; FreeIPA was chosen because it is the product name and covers Red Hat Identity Management. Worth confirming against whatever the catalog will say.🤖 Generated with Claude Code