add use-cases and message-formats for oidc-integration-guide

Author: Michael Troxler

docs/img/active-oidc-providers.png

@@ -0,0 +1,23 @@
+# Public Cloud Integration Guide
+
+This chapter covers a few Mobile-ID integration scenario examples with popular public cloud services.
+
+## Microsoft Azure ADB B2C
+
+Azure Active Directory B2C is a Single-Sign-On (SSO) solution for any API, web, or mobile application. It enables any organization to provide their users with access using identities they already have, such as Mobile-ID.
+
+Mobile-ID is officially supported by Microsoft Azure and the setup is described on their official article.
+
+Microsoft will act as the secure front door to any of these applications and they will worry about the safety and scalability of the authentication platform. Azure will handle things like denial of service or brute force attacks, so that organizations can focus on their core business and stay out of the identity business.
+
+## Amazon Cognito
+
+Amazon Cognito lets you add user sign-up, sign-in, and access control to your web and mobile apps quickly and easily. Amazon Cognito scales to millions of users and supports sign-in with social identity providers, such as Apple, Facebook, Google, and Amazon, and enterprise identity providers via SAML 2.0 and OpenID Connect.
+
+This article explains how to integrate user sign-in with an OpenID Connect IdP such as Mobile-ID.
+
+![use-case-promt-user-credentials](/img/use-case-promt-user-credentials.png)
+
+## RP knows the username
+
+If the request contains a `login_hint` parameter set to `useLDAP:true` but there is no `prompt` parameter, the result will be that the MobileID service will look up the username on the Active Directory (LDAP) to retrieve the user's mobile phone number, before it will eventually start the MobileID authentication.

docs/img/message-formats-classic.png

@@ -0,0 +1,143 @@
+# Message Formats on the Mobile ID App
+
+Mobile ID App screens can present the Data‑To‑Be‑Displayed (DTBD) in two formats.
+
+Use Classic DTBD for short confirmations and when you must support SIM users. Keep messages concise and always include the "DTBD Prefix" (refer to chapter Error! Reference source not found.).
+
+Use Transaction Approval when readability matters (e.g., PSD2 payments, contract consent, step up login verification). Force the App method with Device LoA4, keep within byte limits, and generate the escaped JSON programmatically.
+
+1. **Classic DTBD** (single text line) uses plain UTF‑8 string that is also signed (DTBS).
+
+   Supported by SIM and App methods.
+
+   Length limited and no formatting options.
+
+   ![message-formats-classic](/img/message-formats-classic.png)
+
+
+2. **Transaction Approval** (key/value pairs) is a structured App‑only format that renders a title (type) and one or more key and value rows for improved readability.
+
+   Approve/Cancel becomes active only after the user scrolls to the end if content exceeds one screen.
+
+   RPs request this by sending a JSON object in the dtbd authorization parameter.
+
+    ![message-formats-transcation-approval](/img/message-formats-transcation-approval.png)
+
+
+## Classic DTBD
+
+A single UTF‑8 string shown on the device. The classic DTBD must include the AP‑specific DTBD prefix (e.g., Bank ACME:) and is supported by both SIM and App methods.
+
+Keep the DTBD short. Maximum 239 characters; if any character falls outside the GSM 03.38 set, effective maximum is 119 characters.
+
+Parameter: `dtbd` with a plain string. The OP renders the classic one-line message.
+
+Typical request excerpt:
+
+```bash
+
+...&dtbd=Please%20confirm%20your%20login%20to%20MyBank%20eBanking
+
+```
+
+
+## Transaction Approval
+
+A structured DTBD that the Mobile ID App renders as a title and rows of key/value pairs. If content overflows, the user must scroll to the bottom; only then are Approve/Cancel enabled.
+
+SIM does not support this format. Always select an App ACR (e.g., `mid_al3_mobileapp`).
+
+How to request it: Send a JSON object via the `dtbd` authorization request parameter; the value must be URL-encoded (percent-encoding). If the decoded value starts with `{` and validates against the schema/limits below and the user has an active App, the OP renders the key/value screen.
+
+```json
+{
+  "type": "<ascii>",
+  "dtbd": [
+    { "key": "<ascii>", "value": "<ascii>" }
+    /* up to 20 pairs */
+  ]
+}
+```
+
+Limits (in bytes):
+
+- `type` ≤ 100
+- ≤ 20 pairs
+- each `key` ≤ 100, each `value` ≤ 2000
+- sum(keys+values) ≤ 2000 (bytes; non-ASCII uses 2–4 bytes)
+- DTBD Prefix (required): your configured prefix must be in the value of the first pair
+  e.g., `{"key":"Company","value":"Acme AG: ..."}`
+
+## Transaction Approval Example
+
+### Pretty JSON
+
+Build this first.
+
+```json
+{
+  "type": "Address Change Confirmation",
+  "dtbd": [
+    { "key": "Company",             "value": "Acme AG" },
+    { "key": "Full Name",           "value": "Philipp Haupt" },
+    { "key": "Old Address",         "value": "Bahnhofstrasse 1, 8001 Zürich" },
+    { "key": "New Address",         "value": "Sihlquai 55, 8005 Zürich" },
+    { "key": "Effective Date",      "value": "01 June 2025" },
+    { "key": "Consent Instruction", "value": "Reply APPROVE to consent or CANCEL" }
+  ]
+}
+
+```
+
+### Single-line
+
+What you URL-encode as `dtbd=`
+
+```json
+{"type":"Address Change Confirmation","dtbd":[{"key":"Company","value":"Acme AG"},{"key":"Full Name","value":"Philipp Haupt"},{"key":"Old Address","value":"Bahnhofstrasse 1, 8001 Zürich"},{"key":"New Address","value":"Sihlquai 55, 8005 Zürich"},{"key":"Effective Date","value":"01 June 2025"},{"key":"Consent Instruction","value":"Reply APPROVE to consent or CANCEL"}]}
+
+```
+Below is another example that includes the keywords #CLIENT# and #SESSION#, as described in section 2.2.
+
+```bash
+{"type":"LOGIN","dtbd":[{"key":"Company","value":"#CLIENT#"},{"key":"Session","value":"#SESSION#"}]}
+
+```
+
+### Authorization request (excerpt)
+
+Use PAR to avoid URL length limits and keep parameters confidential.
+Or pass `dtbd` directly on the authorize URL:
+
+```http
+GET /oidc/authorize?
+  response_type=code
+  &scope=openid
+  &client_id=YOUR_CLIENT_ID
+  &state=...
+  &redirect_uri=https%3A%2F%2Fclient.example%2Fcb
+  &acr_values=mid_al3_mobileapp
+  &dtbd=%7B%22type%22%3A%22Address%20Change%20Confirmation%22%2C%22dtbd%22%3A%5B%7B%22key%22%3A%22Company%22%2C%22value%22%3A%22Acme%20AG%22%7D%2C...%5D%7D
+```
+
+Important: Request an App ACR (e.g., `mid_al3_mobileapp`) if you want to ensure the App method is selected.
+
+## What exactly is signed (classic vs. Transaction Approval)
+
+Classic DTBD: the service signs the visible text string.
+
+Transaction Approval: the App signs a normalized JSON object of the form:
+
+```json
+{"format_version":1,"content_string":"[{\"key\":\"Company\",\"value\":\"Test\"}]"}
+```
+
+i.e., the `dtbd` array only; the `type` label is not part of the signed bytes.
+
+## Best practices
+
+- Build → URL-encode → send: generate the JSON with your library, then URL-encode as `dtbd`. Avoid hand-crafted strings. (Use PAR for large payloads/confidentiality.)
+- Select App method: use `acr_values` (e.g., `mid_al3_mobileapp`) when you want to ensure App UX.
+- Prefix rule: include your DTBD prefix in the value of the first pair.
+- Respect byte limits: limits are in bytes, not characters; UTF-8 non-ASCII uses 2–4 bytes.
+- Number-matching & keywords: `#SESSION#` and `#CLIENT#` keywords are supported in `type`, `key`, or `value` and can be used to implement number matching.

docs/img/message-formats-transcation-approval.png

@@ -0,0 +1,28 @@
+# MobileID OIDC - Use Cases
+
+This chapter provides additional guidelines about the various parameter settings in the authorization request.
+
+## Prompt user for MSISDN
+
+If the request does not contain a `login_hint` nor `prompt` parameter, the result will be that the user must enter the phone number on the MobileID side, as shown in the figure below. This is a typical B2C scenario, for example the MobileID login to a public web shop. Note that the Relying Party won't know the user's MSISDN unless the user will give his consent.
+
+![use-case-msisdn-prompt-user](/img/use-case-msisdn-prompt-user.png)
+
+## RP knows the MSISDN
+
+If the request contains a `login_hint` parameter with the user's phone number, the MobileID authenti-cation can start immediately.
+
+![use-case-msisdn-rp-knows](/img/use-case-msisdn-rp-knows.png)
+
+
+## Prompt user for user credentials
+
+If the request contains a `login_hint` parameter set to `useLDAP:true` and a `prompt` parameter set to `login`, the result will be that the user must enter the user credentials on the MobileID side, as shown in the figure below. This is a typical B2B scenario, for example the MobileID login to a company service.
+
+MobileID service will look up the username on the Active Directory (LDAP), verify the user password and retrieve the user's mobile phone number, before it will eventually start the MobileID authentication.
+
+Instead of the MobileID domain (m.mobileid.ch), we can configure your custom domain instead.
+
+![use-case-rp-knows-username](/img/use-case-rp-knows-username.png)
+
+