[#1960] - Add SunbirdRC (KBI) authentication provider

[nandhu-kumar]

Resolves #1960

What

Adds a new authentication provider AUTHN_PROVIDER=sunbird that authenticates
users via Knowledge-Based Identity (KBI) against a SunbirdRC registry, alongside
the existing catalog and mosip providers.

Why

To support SunbirdRC registry-based login in the Go eSignet service, mirroring
the existing Java eSignet Sunbird plugin (io.mosip.esignet.plugin.sunbirdrc).

How it works

• User enters individualId + KBI fields (default fullName, dob).
• These are POSTed as exact-match filters to the registry search endpoint.
• Auth succeeds only when the registry returns exactly one matching entity;
  its entity id (default osid) becomes the user id.
• User attributes are fetched from the registry get endpoint and mapped to
  OIDC claims via configurable claim mapping.
• Reuses the built-in BasicAuthExecutor (no custom executor needed).

Changes

• internal/config/sunbird.go – config + env vars (mirrors the Java property keys)
• internal/host/sunbird_authn.go – the provider (search + attribute fetch + claims mapping)
• Wired into config/authn.go and host/authn_factory.go
• Demo flow flow-declarative-sunbird-1.yaml + app app-declarative-sunbird.yaml
• Unit tests (config, factory, httptest-based provider tests)
• Docs: README.md + .env.example
• Build fix: make keys now works on Windows Git Bash (MSYS path handling)

Testing

• go build ./... and go test ./... pass.
• Verified end-to-end against a live registry: authorize → flow → token returns
  flowStatus: COMPLETE and a valid assertion/access token.

Configuration

Set AUTHN_PROVIDER=sunbird and the MOSIP_ESIGNET_AUTHENTICATOR_SUNBIRD_RC_*
env vars (registry search/get URLs are required). See .env.example.

Summary by CodeRabbit

• New Features

  • Added SunbirdRC authentication provider with KBI-based identity verification, OIDC claims mapping, and optional attribute fetching.
  • Added a declarative Sunbird application and authentication flow enabling registration, recovery, and an OAuth2 client (authorization code, PKCE, public client).

• Documentation

  • Expanded configuration docs and env examples to document SunbirdRC endpoints, KBI field mappings, claim mappings, and timeout defaults.

[coderabbitai]

Warning

Review limit reached

@nandhu-kumar, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 20 minutes and 3 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2a20d61b-1e11-43d7-a898-8524fad2d43e

📥 Commits

Reviewing files that changed from the base of the PR and between 7973522 and 0d49800.

📒 Files selected for processing (13)

• esignet-service/.env.example
• esignet-service/Makefile
• esignet-service/README.md
• esignet-service/data/repository/resources/applications/app-declarative-sunbird.yaml
• esignet-service/data/repository/resources/flows/flow-declarative-sunbird-1.yaml
• esignet-service/internal/config/authn.go
• esignet-service/internal/config/authn_test.go
• esignet-service/internal/config/sunbird.go
• esignet-service/internal/config/sunbird_test.go
• esignet-service/internal/host/authn_factory.go
• esignet-service/internal/host/authn_factory_test.go
• esignet-service/internal/host/sunbird_authn.go
• esignet-service/internal/host/sunbird_authn_test.go

Walkthrough

Adds SunbirdRC (KBI) authentication: environment-driven configuration and defaults, README and .env.example updates, declarative flow and application YAML, a new Sunbird AuthnProvider that validates credentials via HTTP registry search and optionally fetches entity attributes, and factory/tests wiring.

Changes

SunbirdRC Authentication Provider

Layer / File(s)	Summary
Configuration and environment setup esignet-service/internal/config/authn.go, esignet-service/internal/config/sunbird.go, esignet-service/.env.example	Add AuthnProviderSunbird, Authn.Sunbird field, and LoadSunbirdAuthn() with defaults, timeout parsing, and .env documentation for Sunbird variables.
Configuration validation tests esignet-service/internal/config/authn_test.go, esignet-service/internal/config/sunbird_test.go	Tests assert default values, overrides, trailing-slash trimming, and timeout fallback for Sunbird config.
Documentation and declarative resources esignet-service/README.md, esignet-service/data/repository/resources/flows/flow-declarative-sunbird-1.yaml, esignet-service/data/repository/resources/applications/app-declarative-sunbird.yaml	Document AUTHN_PROVIDER=sunbird, SunbirdRC env vars and behavior; add declarative authentication flow and an OAuth2 application resource for Sunbird clients.
Sunbird authentication provider implementation esignet-service/internal/host/sunbird_authn.go	Implement NewSunbirdAuthnProvider, Authenticate (KBI POST search, exact-one-match enforcement, extract entity ID), GetAttributes (optional entity GET and claim mapping), plus JSON parsing helpers and timeouts.
Auth provider tests esignet-service/internal/host/sunbird_authn_test.go	Unit tests covering provider construction validation, Authenticate success/failure scenarios, GetAttributes behavior, and claim-mapping helper.
Factory integration esignet-service/internal/host/authn_factory.go, esignet-service/internal/host/authn_factory_test.go	Add sunbird case to authn factory and tests validating required SearchURL presence.
Build compatibility esignet-service/Makefile	Prefix OpenSSL invocation with MSYS2/Git Bash env vars for correct argument/path handling on Windows environments.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A registry hops into eSignet's embrace,
KBI searches paint trust across the space,
One match is sought, one match is found,
Claims flow back softly, attributes sound.
Sunbird sings and the login finds its place.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title '[#1960] - Add SunbirdRC (KBI) authentication provider' clearly and concisely summarizes the main change: adding a new SunbirdRC Knowledge-Based Identity authentication provider to the system.
Linked Issues check	✅ Passed	The PR comprehensively implements the Sunbird plugin integration objective from issue #1960, including configuration, provider implementation, wiring, demo flows, unit tests, and documentation.
Out of Scope Changes check	✅ Passed	All changes in the PR are directly related to implementing the SunbirdRC authentication provider and its integration. The Makefile change for Windows Git Bash compatibility is a necessary build fix to support development on Windows.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@esignet-service/data/repository/resources/applications/app-declarative-sunbird.yaml`:
- Line 19: app-declarative-sunbird.yaml references an OAuth client_id
"decl-sunbird-client-1" but there is no corresponding OAuth client resource in
the repository; either add a new OAuth client resource named
decl-sunbird-client-1 under the resources layout (create the appropriate
directory and resource YAML describing the client credentials/inbound config) or
change the client_id in app-declarative-sunbird.yaml to match an existing OAuth
client resource; look for functions/entries referencing client_id
"decl-sunbird-client-1" and ensure the new resource uses that exact identifier
so the application inbound auth resolves correctly.

In
`@esignet-service/data/repository/resources/flows/flow-declarative-sunbird-1.yaml`:
- Around line 34-45: The executor input types are inconsistent with the PROMPT:
change the inputs referenced in BasicAuthExecutor so that fullName and dob (and
individualId if intended) use type TEXT_INPUT instead of PASSWORD_INPUT to match
the PROMPT node; update the input definitions in the BasicAuthExecutor block
that reference identifiers fullName, dob, and individualId to TEXT_INPUT so KBI
fields remain non-password fields (only use PASSWORD_INPUT where values must be
masked).

In `@esignet-service/internal/config/sunbird_test.go`:
- Around line 48-54: Add a negative timeout test to
TestLoadSunbirdAuthn_invalidTimeoutFallsBackToDefault to assert
LoadSunbirdAuthn() falls back to the default when envSunbirdTimeout is set to a
negative value; set the environment variable envSunbirdTimeout to "-5" (or any
negative number), call LoadSunbirdAuthn(), and require that TimeoutSecs equals
the default (10) to cover the secs <= 0 branch in sunbird.go.

In `@esignet-service/README.md`:
- Around line 113-114: Add concrete example default JSON for
MOSIP_ESIGNET_AUTHENTICATOR_SUNBIRD_RC_AUTH_FACTOR_KBI_FIELD_DETAILS and
MOSIP_ESIGNET_AUTHENTICATOR_SUNBIRD_RC_IDENTITY_OPENID_CLAIMS_MAPPING in the
README: show a code block with a representative JSON list for the KBI fields and
a JSON map for the OIDC→registry claims mapping (use the exact env var names in
the heading), or add a clear reference/link to the project's .env.example that
contains those values; ensure the examples reflect the insurance defaults and
match the expected keys/structure used by the code that reads these env vars.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 02afb834-eafb-4b8a-8dae-f6a27c01803e

📥 Commits

Reviewing files that changed from the base of the PR and between e47de6d and 6fa7e9b.

📒 Files selected for processing (13)

• esignet-service/.env.example
• esignet-service/Makefile
• esignet-service/README.md
• esignet-service/data/repository/resources/applications/app-declarative-sunbird.yaml
• esignet-service/data/repository/resources/flows/flow-declarative-sunbird-1.yaml
• esignet-service/internal/config/authn.go
• esignet-service/internal/config/authn_test.go
• esignet-service/internal/config/sunbird.go
• esignet-service/internal/config/sunbird_test.go
• esignet-service/internal/host/authn_factory.go
• esignet-service/internal/host/authn_factory_test.go
• esignet-service/internal/host/sunbird_authn.go
• esignet-service/internal/host/sunbird_authn_test.go

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@esignet-service/internal/host/sunbird_authn_test.go`:
- Around line 147-151: Add a regression test to ensure buildSunbirdMappedClaims
fails-closed on malformed SUNBIRD_CLAIMS_MAPPING: create a new test (e.g.,
TestBuildSunbirdMappedClaims_invalidMappingFailsClosed) that calls
buildSunbirdMappedClaims with a valid entity map and a deliberately malformed
mapping string (non-JSON or invalid mapping schema) and assert the result does
NOT equal the original entity and instead returns an empty/safe map (e.g.,
map[string]interface{}{}), enforcing that no raw-entity leakage occurs when
parsing fails.

In `@esignet-service/internal/host/sunbird_authn.go`:
- Around line 229-234: The current error branch in parseSunbirdClaimsMapping
handling (when parseSunbirdClaimsMapping(claimsMappingJSON) returns err)
incorrectly returns raw entityData, risking over-disclosure; change the branch
in the function that calls parseSunbirdClaimsMapping to fail-closed by logging
the parse error with applog.GetLogger().Warn or Error and returning an empty map
(or propagate the error instead of returning entityData) so no registry fields
are passed through—update the error handling around claimsMapping,
claimsMappingJSON, and the return value to ensure an empty map is returned on
parse failure (or surface the error) rather than entityData.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1d1332f5-60c7-47d0-90d1-14c9165ad115

📥 Commits

Reviewing files that changed from the base of the PR and between 6fa7e9b and 7973522.

📒 Files selected for processing (13)

• esignet-service/.env.example
• esignet-service/Makefile
• esignet-service/README.md
• esignet-service/data/repository/resources/applications/app-declarative-sunbird.yaml
• esignet-service/data/repository/resources/flows/flow-declarative-sunbird-1.yaml
• esignet-service/internal/config/authn.go
• esignet-service/internal/config/authn_test.go
• esignet-service/internal/config/sunbird.go
• esignet-service/internal/config/sunbird_test.go
• esignet-service/internal/host/authn_factory.go
• esignet-service/internal/host/authn_factory_test.go
• esignet-service/internal/host/sunbird_authn.go
• esignet-service/internal/host/sunbird_authn_test.go