Abrham Bunaro

Fayda identity integration

PrototypeTeamPublic code2026

A small Node.js service that connects Fairway's apps to Fayda, Ethiopia's national digital ID, through OAuth 2.0 and OpenID Connect.

The problem

Fayda authenticates a client with a signed JWT, not a client secret. A browser or mobile app cannot safely hold the private key that signs it, so the token exchange has to happen on a server.

How it works

An Express 5 service with two endpoints. The token endpoint takes the authorization code, builds an RS256 client assertion with jose and exchanges it at Fayda's token endpoint with PKCE. The user-info endpoint forwards the access token and returns the verified claims.

Helmet, rate limiting and a request-size cap wrap both routes, and upstream failures come back as generic errors.

The sign-in and token exchange
  1. App to Fayda: Send the user to sign in, with a PKCE challenge
  2. Fayda to App: Redirect back with an authorization code
  3. App to Token service: Post the code
  4. Token service to Fayda: Exchange it with a signed client assertion
  5. Fayda to Token service: Return the tokens
  6. Token service to Fayda: Ask for user-info with the access token
  7. Token service to App: Return the verified claims

What I worked on

  • Wrote the service: both routes, the client-assertion signing and the security middleware.
  • Debugged the token exchange against Fayda's responses, including JSON that arrives encoded as a string.

A team project. This list is limited to what the public commit history shows under my name.

Security notes

  • The signing key and client ID live only in the server's environment. The repository holds neither.
  • Requests are rate-limited and bodies are capped at 1 MB.
  • No real identifiers, tokens or national-ID numbers appear in the code or in this write-up.

Where it stands

Published as a public repository under the Fairway organisation. It gives Fairway's web and mobile front ends one place to exchange Fayda authorization codes.

Next project

Compliance oracle

Back to all work