Fayda identity integration
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.
- App to Fayda: Send the user to sign in, with a PKCE challenge
- Fayda to App: Redirect back with an authorization code
- App to Token service: Post the code
- Token service to Fayda: Exchange it with a signed client assertion
- Fayda to Token service: Return the tokens
- Token service to Fayda: Ask for user-info with the access token
- 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.