You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: add hyperlinks to standards, RFCs, and technical references
Link important technical terms to their authoritative sources across
all documentation pages, similar to academic citation practice. Includes
FIPS 140-2, ETSI TS 102 204, OAuth 2.0, JWT, PKCE, PAR, E.164,
GSM 03.38, PSD2, NIST references, CVE-2024-3596, FIDO Metadata Service,
COSE, CMS, EAL5+, TPM, and all RADIUS-related RFCs.
Copy file name to clipboardExpand all lines: docs/oidc-integration-guide/best-practices.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
### Back-channel PAR Submission
6
6
7
-
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.
7
+
The [Pushed Authorisation Request (PAR)](https://datatracker.ietf.org/doc/html/rfc9126) 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.
8
8
9
9
::: info
10
10
Introducing an extra backend call to submit the authorisation parameters has three benefits:
Copy file name to clipboardExpand all lines: docs/oidc-integration-guide/introduction.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,10 @@
2
2
3
3
This document provides Relying Parties (RPs) with technical guidance and best practices for integrating Mobile ID OpenID Provider (MobileID OP) into their applications.
4
4
5
-
The MobileID OP can be used for both authorization and authentication. It fully complies with the OpenID Connect specification.
5
+
The MobileID OP can be used for both authorization and authentication. It fully complies with the [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) specification.
6
6
7
7
::: info OpenID Connect
8
-
OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
8
+
OpenID Connect is a simple identity layer on top of the [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) protocol. It allows clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
9
9
10
10
OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and session management, when it makes sense for them.
11
11
@@ -26,7 +26,7 @@ The most basic key concepts are as follows.
26
26
-**Scopes** are identifiers used to specify what access privileges are being requested.
27
27
-**Claims** are simply key & value pairs that contain information about an End-User, as well as meta-information about the authentication event. Non-standard claims can be specified as custom claims.
28
28
-**Access Token** is a credential used to access protected resources directly. Access tokens usually have an expiration date and are short-lived. They must be kept secret, though security considerations are less strict due to their shorter life.
29
-
-**ID Token** is an identity token provided by the OpenID Provider to the Relying Party. The identity token contains a number of claims about that End-User and also attributes about the End-User authentication event, in a standard JWT format and signed by the OpenID Provider (so it can be verified by the intended recipients). It may optionally be encrypted for confidentiality.
29
+
-**ID Token** is an identity token provided by the OpenID Provider to the Relying Party. The identity token contains a number of claims about that End-User and also attributes about the End-User authentication event, in a standard [JWT](https://datatracker.ietf.org/doc/html/rfc7519) format and signed by the OpenID Provider (so it can be verified by the intended recipients). It may optionally be encrypted for confidentiality.
30
30
-**Refresh Token** carries the information necessary to get a new access token. Refresh tokens can also expire but are rather long-lived.
Copy file name to clipboardExpand all lines: docs/oidc-integration-guide/message-formats.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ Mobile ID App screens can present the Data-To-Be-Displayed (DTBD) in two formats
5
5
::: tip
6
6
Use **Classic DTBD** for short confirmations and when you must support SIM users. Keep messages concise and always include the "DTBD Prefix".
7
7
8
-
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.
8
+
Use **Transaction Approval** when readability matters (e.g., [PSD2](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex%3A32015L2366) payments, contract consent, step up login verification). Force the App method with Device LoA4, keep within byte limits, and generate the escaped JSON programmatically.
9
9
:::
10
10
11
11
1.**Classic DTBD** (single text line) uses a plain UTF-8 string that is also signed (DTBS).
@@ -31,7 +31,7 @@ Use **Transaction Approval** when readability matters (e.g., PSD2 payments, cont
31
31
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.
32
32
33
33
::: warning
34
-
Keep the DTBD short. Maximum **239 characters**; if any character falls outside the GSM 03.38 set, effective maximum is **119 characters**.
34
+
Keep the DTBD short. Maximum **239 characters**; if any character falls outside the [GSM 03.38](https://en.wikipedia.org/wiki/GSM_03.38) set, effective maximum is **119 characters**.
35
35
:::
36
36
37
37
Parameter: `dtbd` with a plain string. The OP renders the classic one-line message.
Copy file name to clipboardExpand all lines: docs/oidc-integration-guide/passkey-authentication.md
+8-4Lines changed: 8 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,9 @@
1
1
# Passkey Authentication (early access)
2
2
3
+
::: warning Early Access — Pilot Phase
4
+
MobileID Passkeys are currently available to **pilot testers only** and are not yet generally available in the production environment. This documentation is published in advance so Relying Parties can prepare their integration. General availability for all customers and users is expected **very soon**. Check back shortly for updates.
5
+
:::
6
+
3
7
MobileID now supports **FIDO2 Passkeys** as an authentication method within the OpenID Connect service. Relying Parties can allow their users to authenticate using MobileID Passkeys - alongside or instead of the existing MobileID SIM, App, and OTP SMS methods.
4
8
5
9
## What Are Passkeys?
@@ -19,13 +23,13 @@ Key characteristics of passkeys:
19
23
20
24
The term "Passkeys" is an **umbrella term** for FIDO2-based authenticators. Under the hood, these can be **platform authenticators** (built into a device, such as Touch ID or Windows Hello) or **roaming authenticators** (external hardware keys, such as a YubiKey). These authenticator types differ significantly in how they store the private key - and this distinction directly impacts the security assurance level they can achieve.
21
25
22
-
For MobileID, one of the most relevant security standards is [**NIST AAL3**](https://pages.nist.gov/800-63-3/sp800-63b.html) (Authentication Assurance Level 3), which specifies the highest level of authentication assurance. To achieve AAL3, the authenticator must be **device-bound** (the private key cannot be exported or synced) and the hardware must be **FIPS 140-2 certified**. Cloud-synced passkeys - while phishing-resistant and suitable for AAL2 - do not meet AAL3 because the private key is exportable across devices.
26
+
For MobileID, one of the most relevant security standards is [**NIST AAL3**](https://pages.nist.gov/800-63-3/sp800-63b.html) (Authentication Assurance Level 3), which specifies the highest level of authentication assurance. To achieve AAL3, the authenticator must be **device-bound** (the private key cannot be exported or synced) and the hardware must be **[FIPS 140-2](https://csrc.nist.gov/pubs/fips/140-2/upd2/final) certified**. Cloud-synced passkeys - while phishing-resistant and suitable for AAL2 - do not meet AAL3 because the private key is exportable across devices.
23
27
24
28
This distinction matters for Relying Parties integrating MobileID: while **MobileID users are free to register any type of passkey** in their [MyMobileID Dashboard](https://mobileid.ch/login), the **RP has full control** over which passkey types are accepted during authentication. Through the passkey claims returned by MobileID (see [Passkey Scope and Claims](#passkey-scope-and-claims)), the RP can enforce specific requirements - for example, accepting only FIPS 140-2 certified, device-bound passkeys for high-assurance use cases.
|**Private key storage**| Stored locally on a single device's secure hardware (e.g., Secure Enclave, TPM) | Synced across devices via encrypted cloud services (e.g., iCloud Keychain, Google Password Manager) |
32
+
|**Private key storage**| Stored locally on a single device's secure hardware (e.g., Secure Enclave, [TPM](https://trustedcomputinggroup.org/resource/tpm-library-specification/)) | Synced across devices via encrypted cloud services (e.g., iCloud Keychain, Google Password Manager) |
29
33
|**Examples**| YubiKey, Windows Hello, hardware security keys | Apple Passkeys, Google Passkeys |
30
34
|**Portability**| Tied to one device; if lost, the passkey is lost | Available on all devices within the user's ecosystem |
31
35
|**NIST AAL3 compliance**| Yes (if FIPS 140-2 certified) | No (private key is exportable) |
@@ -151,8 +155,8 @@ To receive passkey-related claims, add the `mid_passkey` scope to the authorizat
151
155
||`mid_pk_cert_level`| string |`FIPS140-2`\|`CommonCriteria`| Certification level of the authenticator |
152
156
||`mid_pk_created_ts`| number |`1717584000`| When the credential was first registered (Unix epoch) |
153
157
||`mid_pk_last_used_ts`| number |`1717591234`| Last usage timestamp (helps risk engines spot dormant keys) |
154
-
||`mid_pk_aaguid`| string |`2fc0579f-8113-...`| FIDO Metadata Service identifier; maps to authenticator vendor/model |
155
-
||`mid_pk_cred_fingerprint`| string |`pQECAyYgASFY...`| SHA-256 of the credential public key (COSE format) |
||`mid_pk_cred_fingerprint`| string |`pQECAyYgASFY...`| SHA-256 of the credential public key ([COSE](https://datatracker.ietf.org/doc/html/rfc9052) format) |
-**[RFC 6613](https://datatracker.ietf.org/doc/html/rfc6613)** — RADIUS over TCP (updated by [RFC 7930](https://datatracker.ietf.org/doc/html/rfc7930))
21
21
22
22
A larger list of related RFCs can be found in the [Annexes](/radius-interface-gateway-guide/annexes#radius-related-rfcs).
0 commit comments