eCitizen Authorization API v2.0.

0
Submit Application Registration to https://forms.gle/gsgP1nQ9sQ5Vdrx48.

Introduction
eCitizen is the official online portal of the Government of Kenya that facilitates discovery and
access of all government services to citizens, residents, visitors, and diplomats.

This document provides a guide to using the eCitizen Authorization API, which is built on the
OAuth 2.0 and OpenID Connect specifications.

The APIs are intended for use by Government MCDAs that need to allow users to log in to
their applications via eCitizen.
Concepts

OAuth2.0 and OpenID Connect (OIDC)

OAuth2.0 is an open standard for authorization that provides a secure way for websites and
applications to access protected user data without requiring the user to provide their
credentials.
OpenID Connect (OIDC) is an authentication protocol built on top of OAuth2.0 that allows
users to authenticate with a single sign-on (SSO) solution.

The Authorization Code Flow is a process that is used by a client to obtain an access token
from an authorization server. The flow consists of the following steps:

1. The client requests an authorization code from the authorization server.

2. The user authorizes the client to access the protected resources.
3. The authorization server issues an authorization code to the client.
4. The client exchanges the authorization code for an access token from the
authorization server.
5. The client uses the access token to access the protected resources.

Proof Key for Code Exchange (PKCE)

https://tools.ietf.org/html/rfc7636

Proof Key for Code Exchange (PKCE) is an extension to OAuth 2.0 that improves security
for public clients by protecting against man-in-the-middle attacks. It does this by requiring the
client to generate a unique code verifier and code challenge, which are then used to obtain
an authorization code from the authorization server. The code verifier is used to verify the
code challenge, which is used to protect the authorization code from guessing or theft.

To implement the Authorization Code Flow with PKCE, the following steps should be taken:

1. Generate a code verifier and a code challenge. The code verifier is a

cryptographically random string used to associate the authorization request with the
token request. The code challenge is a hashed version of the code verifier.
Code Verifier - https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
- must be at least 43 characters long.
- must be at most 128 characters long.
- See the link above for more information on how to generate this.
Code Challenge - https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
 code_challenge = base64urlencode(sha256(code_verifier))

2. Send the code challenge along with the authorization request.

3. Upon approval, the authorization server will return an authorization code.
4. Exchange the authorization code for a token using the code verifier.

By using the code verifier and code challenge, the client can prove that it is the same one
that initiated the authorization request.

Introspection
Token introspection is the process of verifying the authenticity and integrity of a token to
ensure its validity and prevent tampering.

Getting Started
To get started with this API you will need to have your application registered, providing the
information below:

1. Formal application name: This is the name of the MCDA. It will be displayed to users
who need to authorize your application to access their eCitizen data (Boma Yangu in
the image below).
2. At least one redirect_uri - this is the URI to which the user logging in will be
redirected after they authorize your application. You can provide more than one URL,
e.g. one for production and one for testing.

You can submit this information to https://forms.gle/gsgP1nQ9sQ5Vdrx48 for registration.

Once registered, you will be provided with a client_id and a client_secret. The
client_secret must not be exposed publicly and should only be used in server-to-server
communication.
The API

Requesting Authorization
https://accounts.ecitizen.go.ke/oauth/authorize
While the API supports most of the OAuth 2.0 flows, we require that clients use the
Authorization Code Flow. We recommend using the Proof Key for Code Exchange (PKCE).

Upon clicking on the login button on your website, users will be redirected to eCitizen at the
link provided below, with the parameters outlined.

Without PKCE
https://accounts.ecitizen.go.ke/oauth/authorize?client_id=<YOUR
CLIENT_ID>&redirect_uri=<ONE OF YOUR
REDIRECT_URIS>&response_type=code&scope=openid&state=<YOUR STATE>

With PKCE
https://accounts.ecitizen.go.ke/oauth/authorize?client_id=<YOUR
CLIENT_ID>&redirect_uri=<ONE OF YOUR
REDIRECT_URIS>&response_type=code&scope=openid&state=<YOUR
STATE>&code_challenge=<YOUR CODE
CHALLENGE>&code_challenge_method=S256

Query Parameters
response_type: (required) Set this to code.
client_id: (required) The client ID you received when you first created the application.
redirect_uri: (required) The URL to which the user is sent after the authorization is
complete.
scope: (required) A space-separated list of scopes that identify the resources that your
application could access on the user's behalf. Pass openid
state: (recommended) Data that will be returned to your application as was sent to the
authorization server. Imagine a return_url after login.
code_challenge: (required for PKCE) The generated code challenge.
code_challenge_method: (required for PKCE) The method used to generate the challenge.
Set this to S256.
Authorization
The user can choose to authorize the request (by clicking on Proceed) or deny it (by clicking
on Back).

Proceed
Upon clicking on "Proceed," the user will be redirected to the redirect_uri specified in the
authorization call, with the query parameters code and state. The code is the authorization
code that will be used in the next request to obtain an access token. The state is the same
as what was passed to the authorization request.
If, for example, your redirect_uri is https://my.mcda.go.ke/auth/authorize, the user will be
redirected to
https://my.mcda.go.ke/auth/authorize?code=Ov92TqeYfEzkui0edKABmYEBNcc9k0Sr&state
=%2Fprofile

Back
If the user clicks on Back, effectively denying the request to authorize the application, they
will be redirected to the redirect_uri above, this time with the parameters:-
- error=access_denied, and
- error_description=The resource owner denied the request

https://my.mcda.go.ke/auth/authorize?error=access_denied&error_description=The%2Freso
urce%2Fowner%2Fdenied%2Fthe%2Frequest

Fetching the Access Token

https://accounts.ecitizen.go.ke/oauth/access-token
You will need to have an access token for all calls to eCitizen-protected resources.

After the user returns to your site, the application can exchange the authorization code for an
access token at eCitizen’s oauth/access-token endpoint as shown below

curl -X POST https://accounts.ecitizen.go.ke/oauth/access-token \

-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
-d 'grant_type=authorization_code' \
-d 'code=YOUR_AUTHORIZATION_CODE' \
-d 'redirect_uri=YOUR_REDIRECT_URI' \
-d 'code_verifier=YOUR_CODE_VERIFIER'
Body Parameters
client_id: (required) The client ID you received when you registered the application.
client_secret: (required) The client secret you received when you registered the application.
grant_type: (required) Set this to authorization_code.
code: (required) The code you received in the query string.
redirect_uri: (required) Must be identical to the redirect URI provided in the original
/oauth/authorize request.
code_verifier: (required for PKCE) The code verifier that was originally created.

Response
This API responds with an access token, the token type, and the expiration date. The
payload also includes an ID Token, which is a JWT that contains claims about the
authenticated user and can be decoded to extract user information.

Access Token Introspection

https://accounts.ecitizen.go.ke/api/oauth/token/introspect
Use this API to verify that an access token is still valid.

curl -X POST \
https://accounts.ecitizen.go.ke/api/oauth/token/introspect \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'token=48wJCHeJpUpeGUrDsLXc1AC8gzhgn7HX'

If the token is valid, you will receive an HTTP status code 200 with a JSON payload in the
format:

{
"active": true,
"scope": null,
"token_type": "authorization_code",
"client_id": "278f1ef8168611eebdbf0050560101d6"
}
If the token is invalid - maybe expired - you will receive an HTTP status 200 with a JSON
payload in the format:

{
"active": false
}
Fetching User Information
https://accounts.ecitizen.go.ke/api/user-info

To get the user information, call the /api/user-info endpoint as shown below.
GET https://accounts.ecitizen.go.ke/api/user-
info?access_token=<ACCESS_TOKEN_RETRIEVED_ABOVE>

If the request fails e.g. maybe the access token is expired, you will receive an HTTP status
code 400 with a JSON payload in the format:

{
"error": "invalid_request",
"error_description": "The request is missing a required parameter,
..."
}

If the request is successful, you will receive an HTTP status code 200 with a JSON payload
in the format:

{
"id": 1,
"id_number": "12345678",
"email": "user@ecitizen.com",
"active": true,
"first_name": "John",
"last_name": "Doe",
"surname": "Blah",
"account_type": "citizen",
"mobile_number": "254711000000",
"mobile_verified": true,
"Gender": "m",
"Kra_pin_number": "A1000121",
"dob": "1951-05-28"
}

id_number is National ID Number for citizens, alien ID for aliens (Foreign Residents),
passport number or diplomat id.
account_type can be one of citizen, alien, visitor, or diplomat