Integrate in the sandbox

“Log in with DigiD Ghana” is standard OpenID Connect: the authorization code flow with PKCE. Any OpenID Connect library will do. This page is the short version; every address below is the sandbox, which uses invented people only.

1. Your application

What kind of application you register

Type	How it proves who it is
Web application (server side)	Client secret, sent with HTTP Basic authentication, plus PKCE
Single-page or mobile application	No secret: PKCE only

• Only the authorization code flow is allowed for your client (and refresh tokens, if you ask for offline_access). Other flows that the discovery document lists are not available to you.
• Redirect addresses are matched exactly. They must be https, with no wildcard, no fragment, no user name or password and no IP address. In the sandbox, plain http is accepted only for a loopback address (localhost, 127.0.0.1 or [::1]); a mobile application may also use a reverse-domain custom scheme such as gh.example.app:/callback. At most 10 addresses of 512 characters.
• The application name is shown to the person when they approve the login. It cannot contain “DigiD”.

2. Discover the addresses

Read them from the discovery document instead of copying them:

https://id-staging.digidghana.com/.well-known/openid-configuration

Always check that the iss of every ID token equals this issuer exactly: https://id-staging.digidghana.com.

3. Send the person to log in

Make a random state, a random nonce and a PKCE code_verifier; send the code_challenge (the SHA-256 of the verifier, base64url without padding) with code_challenge_method=S256.

https://id-staging.digidghana.com/oauth2/auth
  ?response_type=code
  &client_id=<your client id>
  &redirect_uri=<one of your registered addresses>
  &scope=openid
  &state=<random>
  &nonce=<random>
  &code_challenge=<S256 of your verifier>
  &code_challenge_method=S256

• PKCE is required for every client. A request without a challenge, or with plain, is refused even though the discovery document mentions plain.
• Scopes: openid, and offline_access if your application was approved for refresh tokens. There are no profile, email or phone scopes.

What the person sees

1. DigiD Ghana asks which device the app is on. On this device: the page opens the app. On another device: the app shows a four-letter verification code, the person types it on the page, the page shows a QR code, and the app scans it.
2. The app says “You are going to log in at:” followed by your application name, and offers Cancel or Log in. Log in asks for the PIN code first.
3. The page continues by itself and sends the person back to your redirect address with code and state. If the person chooses Cancel, or the login expires, you receive an error instead, never a code.

There is no single sign-on session: every login is a fresh approval on the person's phone. A request with prompt=none therefore answers login_required.

4. Exchange the code

Check that state is the one you sent, then call the token address once. A code works once; using it again fails.

curl -s https://id-staging.digidghana.com/oauth2/token \
  --user '<client id>:<client secret>' \
  -d grant_type=authorization_code \
  -d code=<the code> \
  -d redirect_uri=<the same redirect address> \
  -d code_verifier=<your verifier>

A single-page or mobile application sends client_id in the body instead of the --user line. The answer holds an access_token, an id_token, expires_in and, with offline_access, a refresh_token.

5. Check the ID token

Do all of these; skipping one is how logins get forged. What the token contains.

1. The signature, with the key whose kid matches in https://id-staging.digidghana.com/.well-known/jwks.json (RS256 only; refuse any other algorithm, including “none”).
2. iss equals the issuer above, and aud contains your client id.
3. nonce equals the one you sent.
4. exp is in the future.
5. Treat sub as the person's identifier for your application only. It is the same for the same person every time they log in to you and different for every other organisation.

6. Refresh, revoke, and what ends a login

• With offline_access, a refresh token works for a limited time and is replaced at every use. Use the new one each time. Presenting an old refresh token again is treated as theft and the tokens are revoked.
• To stop using a token yourself, send it to https://id-staging.digidghana.com/oauth2/revoke.
• The person can log out everywhere or remove a phone in the app; their tokens and consent for your application are revoked, and your next refresh fails. Handle that by asking them to log in again.
• If DigiD Ghana suspends or revokes your organisation, its clients are removed and logins stop.

7. Errors you may meet

Common answers

What happens	Usual reason
An error page from DigiD Ghana at the start	An unknown client id, a redirect address that does not match exactly, or a missing or plain PKCE challenge
invalid_grant from the token address	The code was used already or expired, the verifier or the redirect address differs, or the refresh token is old
access_denied or login_required at your redirect address	The person cancelled, the login expired, or you asked for no interaction
invalid_client	Wrong or rotated client secret. Rotating a secret ends the old one at once.

For sandbox access or help with an integration, write to info@digidghana.com.