docs: improve readability and image quality across oidc-integration-guide pages

Replace 10 images with higher quality versions extracted from the OIDC
Word document, add new Amazon Cognito config screenshot, and apply the
same readability improvements from the rest-api-guide: frosted-glass
callout banners, better formatting, fixed typos and grammar, proper
cross-references, and consistent heading hierarchy. Add Imprint to
sidebar for parity with rest-api-guide.

Author: phaupt

docs/.vitepress/config.mts

@@ -80,6 +80,10 @@ export default defineConfig({
             { text: 'MobileID OIDC - Use Cases', link: '/oidc-integration-guide/oidc-use-cases' },
             { text: 'Message Formats on the Mobile ID App', link: '/oidc-integration-guide/message-formats' }
           ]
+        },
+        {
+          text: '',
+          items: [{ text: 'Imprint', link: '/oidc-integration-guide/imprint.md' }]
         }
       ],
 

docs/oidc-integration-guide/best-practices.md

@@ -1,44 +1,43 @@
 # Best Practices
 
-### Pushed Authorization Request (PAR)
+## Pushed Authorization Request (PAR)
 
 ### Back-channel submission of authorisation parameters
 
 The Pushed Authorisation Request (PAR) endpoint gives OAuth 2.0 clients a back-channel to post the parameters of an authorisation request to the Mobile ID server, to obtain an opaque URI handle for them, and then continue with the frontend redirection to the authorisation endpoint as usual.
 
+::: info
 Introducing an extra backend call to submit the authorisation parameters has three benefits:
 
-- Frees the authorisation request from any browser URL length limits. They can become an issue with complex requests, such as RAR.
-
-- Keeps the parameters confidential between client and server. Regular requests expose them in the URL query string and hence to the browser, the end-user and logs.
-
-- Confidential OAuth clients will be authenticated up-front, and the request parameters will be checked for errors, before sending the end-user to the authorisation endpoint for login and consent.
-
+- **Frees the authorisation request from any browser URL length limits.** They can become an issue with complex requests, such as RAR.
+- **Keeps the parameters confidential** between client and server. Regular requests expose them in the URL query string and hence to the browser, the end-user and logs.
+- **Confidential OAuth clients will be authenticated up-front**, and the request parameters will be checked for errors, before sending the end-user to the authorisation endpoint for login and consent.
+:::
 
 
 ### PAR Request (POST)
 
 Submits the OAuth 2.0 authorisation request parameters to `/par` to obtain a `request_uri` handle for use at the authorisation endpoint.
 
-Header parameters:
-- `[ Authorization ]` Used for HTTP basic authentication of the client.
-- `Content-Type` Must be set to `application/x-www-form-urlencoded`.
-- `[ Issuer ]` The issuer URL
-- `[ Tenant-ID ]` The tenant ID
+**Header parameters:**
+- `Authorization` — Used for HTTP basic authentication of the client.
+- `Content-Type` — Must be set to `application/x-www-form-urlencoded`.
+- `Issuer` — The issuer URL (optional).
+- `Tenant-ID` — The tenant ID (optional).
 
-Body:
+**Body:**
 - The OAuth 2.0 authorisation request parameters, together with any client authentication parameters.
 
-Success:
-- Code: 200
+**Success:**
+- Code: `200`
 - Content-Type: `application/json`
 - Body: `{object}` The PAR response.
 
 Example PAR request for a confidential client registered for `client_secret_basic` authentication:
 
 ```http
 POST /par HTTP/1.1
-Host: c2id.com
+Host: openid.mobileid.ch
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
 Content-Type: application/x-www-form-urlencoded
 
@@ -47,14 +46,13 @@ response_type=code
 &client_id=fcb5e4f1
 &state=af0ifjsldkj
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
-
 ```
 
 Example PAR request for a public client with PKCE:
 
 ```http
 POST /par HTTP/1.1
-Host: c2id.com
+Host: openid.mobileid.ch
 Content-Type: application/x-www-form-urlencoded
 
 response_type=code
@@ -64,8 +62,6 @@ response_type=code
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
 &code_challenge_method=S256
 &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
-
-
 ```
 
 Example response with a request URI to complete the authorisation:
@@ -80,16 +76,14 @@ Pragma: no-cache
   "request_uri" : "urn:ietf:params:oauth:request_uri:OsL1Z3VqIxAT9R77wB7KCw.5-cQUNt9DygE4XxnYjysnw",
   "expires_in"  : 60
 }
-
-
 ```
 
 ### PAR Response
 
 JSON object with members:
 
-- `request_uri`: The request URI handle to use at the authorisation endpoint.
-- `expires_in`: The configured lifetime of the request URI, in seconds.
+- `request_uri` — The request URI handle to use at the authorisation endpoint.
+- `expires_in` — The configured lifetime of the request URI, in seconds.
 
 Example:
 
@@ -102,56 +96,59 @@ Example:
 
 ## Token and response validation
 
-According to the OIDC specification RPs must ensure that the received tokens are valid. The following chapters summarize the Relying Party's obligations when consuming OIDC/OAUTH tokens and responses.
+According to the OIDC specification, RPs must ensure that the received tokens are valid. The following chapters summarize the Relying Party's obligations when consuming OIDC/OAUTH tokens and responses.
 
 ### Authentication Request
 
 Provide state and nonce values with sufficient entropy.
 
-- [http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
-- [http://openid.net/specs/openid-connect-core-1_0.html#NonceNotes](http://openid.net/specs/openid-connect-core-1_0.html#NonceNotes)
+- [OIDC Core — AuthRequest](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
+- [OIDC Core — NonceNotes](http://openid.net/specs/openid-connect-core-1_0.html#NonceNotes)
 
 ### Validate authentication responses
 
 Handle the state parameter correctly.
 
-- [http://openid.net/specs/openid-connect-core-1_0.html#AuthResponseValidation](http://openid.net/specs/openid-connect-core-1_0.html#AuthResponseValidation)
+- [OIDC Core — AuthResponseValidation](http://openid.net/specs/openid-connect-core-1_0.html#AuthResponseValidation)
 
 ### Validate token endpoint responses
 
-Validate the ID Token and proof scopes.
+Validate the ID Token and verify scopes.
 
-- [http://openid.net/specs/openid-connect-core-1_0.html#TokenResponseValidation](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponseValidation)
+- [OIDC Core — TokenResponseValidation](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponseValidation)
 
 ### Validate ID token
 
 Relying Party must validate ID Tokens.
 
-- [http://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation](http://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation)
+- [OIDC Core — IDTokenValidation](http://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation)
 
 ### Protect Client ID and secret
 
-Relying Party's credentials (for example, client secret) must be stored safely for remaining a secret only known by the Relying Party. Relying Party should inform the Mobile ID OP in case credentials have been compromised.
+::: warning
+Relying Party's credentials (for example, client secret) must be stored safely to remain a secret only known by the Relying Party. Relying Party should inform the Mobile ID OP in case credentials have been compromised.
+:::
 
 ### Store tokens securely
 
+::: warning
 Tokens, especially Refresh Tokens, must be treated as credentials and stored securely in a place where only the End-Users for whom they were issued can access them.
+:::
 
 ## Test Users
 
-There are test user accounts available for testing and debugging purpose.
+There are test user accounts available for testing and debugging purposes.
 
-Please be aware, due to the strict phone number validation during the Mobile ID authorization flow, these test phone numbers will only be accepted by the Mobile ID server if they are provided via `log-in_hint` request parameter. However, your account must be authorized to use the `login_hint` parameter and requires the use of Pushed Authorisation Requests (PAR), which keeps the parameters confidential between client and server (see section [Pushed Authorization Request (PAR)](/oidc-integration-guide/best-practices#pushed-authorization-request-par) ).
+::: info
+Due to the strict phone number validation during the Mobile ID authorization flow, these test phone numbers will only be accepted by the Mobile ID server if they are provided via the `login_hint` request parameter. Your account must be authorized to use the `login_hint` parameter and requires the use of Pushed Authorisation Requests (PAR), which keeps the parameters confidential between client and server (see section [Pushed Authorization Request (PAR)](/oidc-integration-guide/best-practices#pushed-authorization-request-par)).
+:::
 
 | MSISDN | Auth | Description |
 |--------|------|-------------|
-| +41-700092501 | SIM | Robot User (EC key; Swisscom Root CA 2 Certificate) |
-| +41-700092502 | SIM | Robot User (RSA key; Swisscom Root CA 2 Certificate) |
-| +41-000092401 | SIM | Simulated user to test the Mobile ID Error 401; USER_CANCEL |
-| +41-000092402 | SIM | Simulated user to test the Mobile ID Error 402; PIN_BLOCKED |
-| +41-000092403 | SIM | Simulated user to test the Mobile ID Error 403; CARD_BLOCKED |
-| +41-000092404 | SIM | Simulated user to test the Mobile ID Error 404; NO_KEY_FOUND |
-| +41-000092406 | SIM | Simulated user to test the Mobile ID Error 406; PB_SIGNATURE_PROCESS |
-
-
-
+| `+41-700092501` | SIM | Robot User (EC key; Swisscom Root CA 2 Certificate) |
+| `+41-700092502` | SIM | Robot User (RSA key; Swisscom Root CA 2 Certificate) |
+| `+41-000092401` | SIM | Simulated user to test the Mobile ID Error 401; USER_CANCEL |
+| `+41-000092402` | SIM | Simulated user to test the Mobile ID Error 402; PIN_BLOCKED |
+| `+41-000092403` | SIM | Simulated user to test the Mobile ID Error 403; CARD_BLOCKED |
+| `+41-000092404` | SIM | Simulated user to test the Mobile ID Error 404; NO_KEY_FOUND |
+| `+41-000092406` | SIM | Simulated user to test the Mobile ID Error 406; PB_SIGNATURE_PROCESS |

docs/oidc-integration-guide/cloud-integration-guide.md

@@ -1,19 +1,23 @@
 # Public Cloud Integration Guide
 
-This chapter covers a few Mobile-ID integration scenario examples with popular public cloud services.
+This chapter covers a few Mobile ID integration scenario examples with popular public cloud services.
 
-## Microsoft Azure ADB B2C
+## Microsoft Azure AD 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.
+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.
+::: info
+Mobile ID is officially supported by Microsoft Azure and the setup is described on their [official article](https://learn.microsoft.com/en-us/azure/active-directory-b2c/identity-provider-generic-openid-connect).
+:::
 
 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.
+::: tip
+This [article](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-oidc-idp.html) explains how to integrate user sign-in with an OpenID Connect IdP such as Mobile ID.
+:::
 
-![use-case-prompt-user-credentials](/img/use-case-prompt-user-credentials.png)
+![amazon-cognito-config](/img/amazon-cognito-config.png)