> For the complete documentation index, see [llms.txt](https://docs.esignet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.esignet.io/home/esignet-2.0.0/develop/integration/authenticator.md).

# Authn Provider

### What an Authn Provider Does

An Authn Provider is the bridge between eSignet and an identity system. eSignet itself never talks to your identity system directly — it delegates that entirely to the Authn Provider, and limits its own responsibility to the parts that are the same for every deployment: OAuth2/OIDC/FAPI protocol compliance, consent capture and enforcement, and token issuance (ID token, access token) plus JWKS publishing.

The Authn Provider, in turn, is responsible for:

* Authenticating the user against the identity system
* Resolving a stable, provider-specific identifier for the authenticated user
* Fetching verified user attributes (KYC data) for whichever claims the user consented to share
* Returning all of that to eSignet in an agreed structure

Because the boundary between the two is a Go interface rather than a network protocol, the identity system behind an Authn Provider can be anything — a single database table for local testing, or a full national identity registry. eSignet only depends on the interface being implemented correctly, never on how the identity system itself is built. This is what replaces the Java version's separate "Authenticator Plugin" concept — same role in the integration, now expressed as a single Go interface.

### Who Should Implement This

Any organization — public or private — that wants to connect its own identity system to eSignet implements this interface.

### How It Works

The engine makes, at most, four calls into an Authn Provider during a login, always in this order — `SendOTP` only fires for OTP-based factors, and each `Get*` call only fires when the corresponding token from `Authenticate` is non-nil:

```
SendOTP           →  Authenticate        →  GetEntityReference   →  GetAttributes
(send-otp screen)    (kyc-auth: verify      (resolve/cache the      (kyc-exchange: fetch
                      the entered OTP/       "sub" claim for         only the consented
                      password/biometric)    consent + token         claims, after consent)
                                              issuance)
```

`Authenticate` can return either an opaque token (for `GetEntityReference` or `GetAttributes` to resolve later) or the resolved value directly — if you return the value directly, the engine skips the corresponding `Get*` call entirely.

*TBA - Sequence Diagram*

### The Interface

A provider is a Go package implementing `shared.ConsolidatedAuthnProvider`, which embeds the engine-level `providers.AuthnProviderInterface` and adds two eSignet-specific methods:

```go
type ConsolidatedAuthnProvider interface {
    providers.AuthnProviderInterface

    SendOTP(ctx context.Context, identifiers map[string]interface{},
        metadata *providers.AuthnMetadata) (*SendOTPResult, *common.ServiceError)

    GetSigningCertificates(ctx context.Context) ([]CertificateData, *common.ServiceError)
}
```

Including the embedded interface, a full implementation has eight methods in total. Three of them (`InitiateAuthentication`, `InitiateEnrollment`, `Enroll`) exist only for the engine's built-in passkey/WebAuthn executor, which none of eSignet's shipped flows currently use — you can safely stub these out unless you add a flow that exercises that path. The full method signatures, supporting types, and error-handling conventions are in the deep dive.

### A Reference Implementation

* **Mock** — talks to a mock identity system over HTTP; supports OTP, password, PIN, biometrics, and arbitrary KBI, with no cryptographic envelope on the payload. It's what Quickstart's Local Setup runs against, so it's the easiest place to see a real, working Authn Provider without standing up a production identity system. `internal/engine/mock`
* **MOSIP IDA** and **SunbirdRC** — the other two reference implementations, adding request encryption/signing and registry-search behavior respectively. Full detail in the deep dive. `internal/engine/mosip` · `internal/engine/sunbird`

### How to Register a New Provider

Providers are compiled into the binary at build time — there's no dynamic loading, no `.so` files, no registry. To add one:

1. Create a new package under `esignet-service/internal/engine/<yourprovider>/`, following the existing file layout (`authenticator.go`, `config.go`, `init.go`, `model.go`).
2. Implement `shared.ConsolidatedAuthnProvider` on a type in `authenticator.go`.
3. Add an `Init(...)` function that also returns an audit sink — your own, or `shared.NewNoopAuditor()` if you don't have one (see [Audit Plugin](/home/esignet-2.0.0/develop/integration/audit.md)).
4. Add a `case "<yourprovider>":` branch to the provider factory's switch statement.
5. Rebuild.

Which provider actually runs at startup is chosen by the `MOSIP_ESIGNET_AUTHN_PROVIDER` environment variable (default `mock`).

### Further Details

The Authn Provider Deep Dive *(Link TBA)* has the full interface and supporting-type definitions, the error-handling conventions, the exact `identifiers`/`credentials` field split per auth factor, configuration conventions, and the full reference-implementation comparison table for Mock, MOSIP IDA, and SunbirdRC.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.esignet.io/home/esignet-2.0.0/develop/integration/authenticator.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.