SSO authentication

This document explains how external service providers can implement Single Sign-On (SSO) for embeds in the Mijn Burgerprofiel mobile app.

Disclaimer: This document changes as the implementation evolves. Contact the Mijn Burgerprofiel team if you have questions or feedback.

Introduction

When a user opens an embed that requires authentication from the Mijn Burgerprofiel app, the SSO flow passes the app's existing session context to the embed. The user does not need to sign in again.

The flow uses Vlaams Toegangsbeheer (ACM) and a token exchange mechanism. Sensitive tokens stay on the server and are never exposed directly to the frontend.

SSO flow overview

The following sequence shows the responsibilities of each system:

App          MBP backend         ACM        Embed backend       Embed
 |                |               |               |               |
1. Request SSO    |               |               |               |
 |---------------->               |               |               |
 |                |               |               |               |
 |                2. Token exchange               |               |
 |                |--------------->               |               |
 |                |               |               |               |
 |                3. Access token for the embed backend           |
 |                <---------------|               |               |
 |                |               |               |               |
 |                4. Register the access token    |               |
 |                |------------------------------->               |
 |                |               |               |               |
 |                5. Handover token               |               |
 |                <-------------------------------|               |
 |                |               |               |               |
6. Handover token |               |               |               |
 <----------------|               |               |               |
 |                |               |               |               |
7. Open embed with ?token=<handover-token>        |               |
 |---------------------------------------------------------------->
 |                |               |               |               |
 |                |               |   8. Resolve the handover token
 |                |               |               <---------------|
 |                |               |               |               |
 |                |               |           9. Create the session
 |                |               |               |--------------->
 |                |               |               |               |
Copy

Steps

Step-up authentication for an open embed

The normal flow authenticates the user before the embed opens. Step-up authentication starts from an embed that is already open. The embed asks the host for a sign-in handover token when it needs one.

This is useful when:

• the embed opened without an initial token parameter
• the user needs to sign in after reaching a protected action
• the initial handover token expired or was already consumed
• a newly opened embed needs its own handover token

The step-up flow reuses the same server-side Token Exchange and token registration flow described above. The difference is how the flow starts and how the handover token reaches the embed. The step-up flow returns the token through the SDK instead of adding it to the embed URL.

Step-up flow

App        MBP backend       ACM    Embed backend       SDK         Embed
 |              |             |           |              |            |
 |              |             |  1. Frontend calls auth.requestSignIn()
 |              |             |           |              <------------|
 |              |             |           |              |            |
 |              |             | 2. SDK sends requestSignIn            |
 <-------------------------------------------------------|            |
 |              |             |           |              |            |
3. App requests step-up SSO   |           |              |            |
 |-------------->             |           |              |            |
 |              |             |           |              |            |
 |              4. Token Exchange         |              |            |
 |              |------------->           |              |            |
 |              |             |           |              |            |
 |              5. Access token for embed backend        |            |
 |              <-------------|           |              |            |
 |              |             |           |              |            |
 |              6. Register access token  |              |            |
 |              |------------------------->              |            |
 |              |             |           |              |            |
 |              7. Handover token         |              |            |
 |              <-------------------------|              |            |
 |              |             |           |              |            |
8. Handover token             |           |              |            |
 <--------------|             |           |              |            |
 |              |             |           |              |            |
9. SDK receives SignInResult  |           |              |            |
 |------------------------------------------------------->            |
 |              |             |           |              |            |
 |              |             |            10. SDK returns SignInResult
 |              |             |           |              |------------>
 |              |             |           |              |            |
 |              |             |           |  11. Resolve handover token
 |              |             |           <---------------------------|
 |              |             |           |              |            |
 |              |             |           12. Start embed session     |
 |              |             |           |--------------------------->
 |              |             |           |              |            |
Copy

Request a sign-in handover token

The embed sends no configuration with the request:

const result = await mbpClient.auth.requestSignIn();

if (result.status === 'success') {
  // Send this handover token to your backend through the normal
  // token-resolution flow. It is not an ACM access token.
  await resolveHandoverToken(result.token);
}
Copy

The host decides which SSO configuration to use from trusted app state. The embed itself cannot choose the SSO client, ACM audience, scopes, token registration endpoint, or prompt text (these are set up in embed configuration in advance).

Call requestSignIn() when the user starts an action that needs authentication, or when the embed knows it needs a new handover token. Avoid calling it repeatedly in render logic or on every route change. The host can reject duplicate requests.

The SDK waits up to 120 seconds for the host to return a result. A timeout or another messaging failure rejects the promise. Expected outcomes are returned as a SignInResult instead.

Messages in non-success results are for debugging. Keep them out of user-facing copy.

Treat cancelled as a normal user outcome, not as a technical error. Let the user continue unauthenticated or offer a retry action if that fits your flow.

If the user is not signed in to the host application, the host may show a login UI as part of the step-up flow. If login succeeds, the request can still return success. If login is closed, declined, or fails technically, the result will be cancelled or failed.

Host prompt and consent behavior

The app may ask the user for consent the first time an embed client requests step-up SSO. After the user accepts, later requests from embeds using the same configured client may complete without another prompt while the user remains signed in to the host application.

This only skips the prompt. The host still requests a new handover token for every successful requestSignIn() call. Do not cache and reuse a successful handover token.

If the user logs out of the host application, the remembered step-up consent is cleared. A later login may require consent again.

Multiple embeds that use the same configured client can share the same app-side step-up consent. A newly opened embed can call requestSignIn() and receive a new handover token without another prompt if the user already accepted step-up SSO for that client during the current app login.

Keep both flows available

Step-up authentication does not replace the initial URL-token flow. A provider can support both:

• an initial handover token from ?token=...
• a step-up handover token from mbpClient.auth.requestSignIn()

Both tokens can use the same provider-side token resolution endpoint. Handover tokens are short-lived and must be single-use.

Requirements

To implement SSO for your embed, you need to:

1. Request a trust configuration from Vlaams Toegangsbeheer.

   Email integraties@vlaanderen.be with:

   • A description of your use case
   • Any existing ACM clients you already use

   CC app.mbp@vlaanderen.be on the email so the Mijn Burgerprofiel team can follow the request.

2. Implement the token registration endpoint on your backend: POST /auth/v1/token.

3. Add frontend logic to read the handover token from the URL and exchange it for a session.

4. Add step-up logic if needed by calling mbpClient.auth.requestSignIn() when an open embed needs a new handover token.

Backend implementation: token registration endpoint

Your backend needs an endpoint where the MBP backend can register an access token in exchange for a temporary handover token.

Endpoint

POST /auth/v1/token
Content-Type: application/json
Copy

Request

The MBP backend sends the access token it received through Token Exchange:

{
  "token": "<ACCESS-TOKEN>"
}
Copy

Validate the access token and retrieve user information

Validate the access token with the ACM introspection endpoint. This confirms that the token:

• Is valid and has not expired
• Contains the correct audience for your client
• Comes from a trusted source

The introspection response also contains user information that you can use to create the session.

Important: The userinfo endpoint only works with ID tokens. Use the introspection endpoint for access tokens received through Token Exchange.

See Validate an access token for implementation details.

Example introspection response

The introspection endpoint returns information such as:

{
  "iss": "https://authenticatie-ti.vlaanderen.be/op",
  "active": true,
  "exp": 1768862219,
  "iat": 1768858619,
  "client_id": "111b330d-56f1-47c5-b8a0-ddc171efdd41",
  "aud": "<your client ID>",
  "scope": "rrn vo_info profile delegation",
  "rrn": "85251512381",
  "given_name": "First name",
  "family_name": "Last name",
  "leeftijd": "40",
  "jwt": "eyJhbGciOiJSUzI1NiIs..."
}
Copy

Relevant claims for identifying the user:

What to do with the access token

After validation:

1. Store the access token on the server for the embed session.
2. Extract the user information from the introspection response.
3. Associate the information with the handover token you generate.

Important: Never send the access token to the frontend. Store it securely on your backend and associate it with the handover token.

Response

Generate a temporary handover token and return it.

Success (200 OK):

{
  "token": "<HANDOVER-TOKEN>"
}
Copy

Error handling

Example error response:

{
  "error": "Invalid or expired token"
}
Copy

Frontend implementation: process the handover token

When the embed opens, the frontend receives the handover token as a query parameter:

https://example.com/embed?token=<HANDOVER-TOKEN>
Copy

Start a session

1. Read the token query parameter from the URL.
2. Send the handover token to your backend.
3. Let your backend validate the token and start a session.

Important: Never request the original access token from the frontend. The handover token only starts the session. Your backend handles all further authentication through the server-side session.

Error handling

Security

Handover token recommendations

Access token security

Environments

Mijn Burgerprofiel app client IDs

Request a trust relationship for the relevant client ID from Vlaams Toegangsbeheer:

Development and testing process

1. TNI environment: ACM creates a client for the TNI test environment.
2. Validation: Test your integration thoroughly in TNI.
3. Production: After successful validation, ask ACM to move the configuration to production.

Note: Your application's client ID will probably differ between TNI and production.

Related documentation

OpenAPI specification

{
  "openapi": "3.0.2",
  "info": {
    "title": "Mijn Burgerprofiel - SSO Token",
    "version": "1.0"
  },
  "components": {
    "schemas": {
      "RequestToken": {
        "type": "object",
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Token received through IdP Token Exchange"
          }
        }
      },
      "ResponseTempToken": {
        "type": "object",
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Temporary SSO handover token"
          }
        }
      },
      "ClientError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        }
      },
      "ServerError": {
        "type": "string"
      }
    }
  },
  "servers": [
    {
      "description": "Your embed backend",
      "url": "https://embed.example.be"
    }
  ],
  "paths": {
    "/auth/v1/token": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestToken"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The request was accepted and a temporary token was generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseTempToken"
                }
              }
            }
          },
          "400": {
            "description": "The request is missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          },
          "401": {
            "description": "The token in the request is invalid or expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          },
          "500": {
            "description": "The application encountered an unexpected error while processing the token",
            "content": {
              "text/html": {
                "schema": {
                  "$ref": "#/components/schemas/ServerError"
                }
              }
            }
          }
        }
      }
    }
  }
}

Vlaams Toegangsbeheer (ACM)

• Token Exchange overview - General information about Token Exchange
• Request Token Exchange - Request a trust configuration
• Validate an access token - Token introspection endpoint

Standards

• RFC 8693 - OAuth 2.0 Token Exchange