Authenticate citizens with eSignet over Base Registry Engine (BReg)

You run a population or civil registry on Base Registry Engine (BReg) and you want citizens to sign in to public services with eSignet, the open-source identity and authentication service from the MOSIP project. The eSignet BReg provider is the piece that connects the two. It lets eSignet resolve a verified identifier against your registry through one governed lookup, and release only the demographic claims each citizen approves. This page explains what the provider does, what your registry must grant it, and what it deliberately leaves out. It is the adopter-facing account of registrystack/esignet-relay-authenticator v0.3.0.

Who owns what

eSignet owns the login experience and the OpenID Connect (OIDC) surface: the relying-party registration, the authorization and token endpoints, the consent screen, and the signing and optional encryption of ID Tokens and UserInfo responses. Relying parties talk to eSignet only. They never see BReg.

BReg owns the registry: the population records, the access profiles that decide which client may read which fields, the revision history, and the audit journal. It knows nothing about eSignet as a product. From its side, the provider is one more client with one narrow grant.

Registry Mint issues the short-lived access token the provider presents to BReg. The provider authenticates to Mint as a registered private_key_jwt client and never holds a long-lived registry credential.

The provider itself is a Go module compiled into the eSignet host. eSignet selects it by setting the authentication provider to breg and pointing it at one YAML configuration file. The provider contributes three things: it verifies the citizen’s challenge, it performs the governed lookup, and it derives the claims and the pairwise subject that eSignet then signs. Everything else stays with eSignet.

The login flow

A login takes two round trips into your registry at most, and none until the citizen has proved possession of their identifier.

sequenceDiagram
    participant C as Citizen
    participant E as eSignet
    participant P as BReg provider
    participant M as Registry Mint
    participant B as BReg

    C->>E: Enter identifier, receive challenge
    C->>E: Submit challenge response
    E->>P: Verify challenge
    P->>M: private_key_jwt client_credentials
    M-->>P: Short-lived access token
    P->>B: Lookup account-check fields only
    B-->>P: uin, status
    E->>C: Consent screen (requested claims)
    C->>E: Approve a subset
    E->>P: Fetch approved claims
    P->>B: Lookup approved fields only
    B-->>P: Selected domain data
    P-->>E: Claims plus pairwise subject
    E-->>C: Signed ID Token and UserInfo

The order matters for data protection:

1. Challenge first. The provider verifies the citizen’s one-time code or other challenge before any registry call. A wrong code never reaches BReg or Mint, so the registry is not an oracle for guessing identifiers.
2. Account check with the smallest projection. After a correct challenge, the provider looks up the identifier and asks BReg for only the fields named in account_check_fields, typically the identifier and a status field. Which records resolve at all is the access profile’s decision: a profile scoped to active records makes inactive ones unresolvable, and the provider reports that as a denied subject.
3. Fresh consent every time. eSignet shows the consent screen on every login. The provider installs no remembered consent, so a citizen who approved their birthdate last month is asked again today.
4. Second lookup limited to the approved intersection. The provider computes the intersection of the claims the citizen approved, the claims named in claim_map, and the fields the access profile provisions. It asks BReg for exactly that set. If the intersection is empty, it makes no call at all.
5. Only domain data becomes claims. The provider reads the record’s domain data and ignores envelope metadata such as revision numbers, timestamps, and links.

Authentication state between the challenge and consent steps is held server-side for five minutes and bound to the relying party, the client, and the transaction. A context that expires or is presented by a different party fails with a dedicated error code rather than a silent retry.

The governed lookup

The provider reaches your registry through a single fixed BReg operation: a lookup on the route you name, with the selector you name, under the access profile you grant. On the wire that is a POST to the route’s :lookup operation, with accessProfile and $select query parameters and a JSON body carrying the selector and the verified identifier.

POST /v1/records/population:lookup?accessProfile=esignet-source&$select=uin,status
Authorization: Bearer <Mint access token>
Content-Type: application/json
Accept: application/json

{"selector":"by-uin","values":{"uin":"<verified identifier>"}}

The $select list is never wider than the configured provisioned fields, and BReg enforces the same ceiling on its side through the access profile. A misconfigured provider that asked for more than the profile grants receives a denial, not extra data.

What your registry must grant

On the BReg side, integration is an access-control decision expressed in the registry project, not a code change. The provider needs:

• One selector profile on the population route, for example by-uin, that resolves exactly one record from one identifier field. The provider fails rather than picking among several matches.
• One access profile dedicated to eSignet, for example esignet-source, granting only the lookup operation and only the fields the provider may ever project. Leave get, list, and all write operations out of it. The provider never lists or writes, so a profile that permits either is wider than the integration needs.
• A required scope only the provider holds. accessProfile is a request parameter, so the profile’s name isolates nothing on its own: any authenticated caller whose token satisfies the profile’s principal claim, purposes, and row boundaries can select it. Give the profile a requiredScopes entry, for example registry:esignet:lookup. A profile with no required scope raises access.profile.no_required_scope when you check the project.
• A field list that mirrors the profile. The provider’s provisioned_fields must match what the profile grants, and account_check_fields must be a non-empty subset of it that contains the selector field. Keep the account check to the identifier and a status field.
• A separate administrative client for anyone who edits records. The eSignet client’s key is lookup-only by construction, and it stays that way only if nobody reuses it for change requests.

On the Mint side, register the provider as a private_key_jwt client with an ES256 or RS256 key, and put the profile’s required scope in that client’s authorization.scopes and nowhere else. The provider’s token request carries no scope of its own, so the registration is the only thing that lets it select the profile. Mint issues tokens the BReg access profile trusts, and the provider caches each one for at most five minutes.

The pages on BReg access profiles, Registry Mint, and governed registry actions explain the surrounding model.

Claims and the pairwise subject

claim_map in the provider configuration ties each OIDC claim name to a registry field. Three rules shape it:

• The subject is never a registry identifier. claim_map.sub must be the literal $psut. The provider derives a pairwise pseudonymous subject per relying party and client, as a base64url HMAC-SHA256 over the tuple of a fixed version string, the relying party, the client, the identifier type, and the identifier, keyed by a secret of at least 32 bytes read from a mounted file. Two relying parties therefore receive different subjects for the same citizen, and neither can recover the registry identifier from its value.
• Only mapped fields can ever leave. A field that the access profile grants but claim_map omits is never requested. A claim the citizen approves that is not mapped is silently absent.
• eSignet signs, the provider does not. The provider returns plain claims and the subject. Signing, JWE encryption for relying parties that request it, and key rotation are eSignet’s.

An eSignet ID Token or UserInfo JWT authenticates a citizen to a relying party. It is not a registry credential. BReg and Evidence Gateway verify access tokens against their configured issuer and required token type, so forwarding a citizen’s ID Token to either one is rejected. The only credential that reaches the registry is the provider’s own Mint access token.

Failure behaviour

The provider collapses registry-side failures into a fixed set of error codes so that a relying party or a citizen never learns whether an identifier exists, is inactive, or is concealed:

Code	When
registry_auth_invalid_request	The request to the provider is malformed or the configuration rejects it.
registry_auth_challenge_failed	The one-time code or other challenge did not verify. No registry call was made.
registry_auth_subject_denied	The lookup resolved no record the profile may disclose.
registry_auth_unavailable	Mint or BReg did not answer within the configured timeout, returned an oversized body, redirected, or omitted a configured account-check field.
registry_auth_context_invalid	The authentication context does not match the relying party, client, or transaction.
registry_auth_context_expired	The five-minute authentication context has lapsed.

Outbound calls require HTTPS unless you explicitly allow insecure HTTP for a local fixture. They carry a bounded timeout (10 seconds by default), a bounded response size (1 MiB by default), and follow no redirects. The provider never logs selectors, tokens, or source values.

A configuration example

The full grammar lives with the provider. This example shows the shape and the relationships the earlier sections described.

subject_id_type: uin
psut_secret_file: /run/secrets/registry-psut
breg:
  base_url: https://population.example.org
  route: population
  selector: by-uin
  selector_field: uin
  access_profile: esignet-source
  provisioned_fields: [uin, status, givenName, familyName, birthdate, gender]
  account_check_fields: [uin, status]
mint:
  token_endpoint: https://mint.example.org/token
  client_id: esignet-source
  private_key_file: /run/secrets/registry-client.jwk
claim_map:
  sub: $psut
  given_name: givenName
  family_name: familyName
  birthdate: birthdate
  gender: gender
http:
  timeout_seconds: 10
  max_response_bytes: 1048576
demo:
  static_otp_enabled: false

Secrets arrive as mounted files, never as inline values or environment variables. The pairwise subject secret and the Mint client key are the two the deployment must protect and rotate on its own schedule.

The demo verifier is for fixtures only

The demo block enables a synthetic one-time code verifier that reads codes from a static file. It exists for fixtures such as Solmara Lab. Production deployments supply a real challenge verifier through the provider’s Go interface, and the host refuses to start with no verifier configured.

Boundaries

Version 0.3.0 draws its lines deliberately:

• BReg only. The provider reads from a Base Registry Engine registry. Reading through Registry Relay is deferred, and Evidence Gateway is not involved: an eSignet login is an authentication, not a signed minimum-disclosure assertion.
• No production challenge delivery. Sending one-time codes over SMS or email, enrollment, wallet-based login, and identity assurance levels are out of scope. Deployments bring their own verifier.
• No Java path. Earlier releases shipped a Java authenticator and JAR injection. Version 0.3.0 replaces them with the Go provider, strict YAML, and mounted secret files, with no compatibility layer.
• Source-integrated build. The provider is compiled into a pinned eSignet release rather than loaded as a plugin, and ships as an OCI image with checksums, an SBOM, and provenance. Publishing that image and running it as a hosted service are separate operator actions.

Try it in Solmara Lab

Solmara Lab carries a synthetic population registry authored for BReg and an isolated eSignet fixture that embeds this provider. Its journey exercises each guarantee above in order: a wrong code is rejected before any registry call, the account check projects only the identifier and status, consent is explicit and can be refused on a later login, a missing required claim ends the login, and the relying party verifies the signed UserInfo and correlates the pairwise subject. It also proves the negative: the eSignet client cannot list, cannot write, and cannot read inactive or ungranted records or fields.

Next

• Configure BReg access profiles to define the lookup-only grant.
• Run Registry Mint and register the provider as a private_key_jwt client.
• Request an access token to test the grant before wiring eSignet.
• BReg HTTP API reference for the lookup route and problem documents.
• Data minimization and purpose limitation for the principles this integration applies.