Skip to content

Commit fbac4c7

Browse files
author
Michael Troxler
committed
add some content to reference-guide
1 parent 05ff66f commit fbac4c7

4 files changed

Lines changed: 326 additions & 1 deletion

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ export default defineConfig({
88

99
themeConfig: {
1010
// https://vitepress.dev/reference/default-theme-config
11-
logo: '/img/mobileid.svg',
11+
logo: 'docs/img/mobileid.svg',
1212

1313
nav: [
1414
{ text: 'Home', link: '/' },

‎docs/reference-guide/auto-activation.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Auto Activation
2+
## Introduction
3+
Auto Activation is an optional feature for APs, which can greatly improve the user experience for Mobile ID SIM authentications. It is applicable for SIM authentication only and this Auto Activation feature is not relevant for Mobile ID App authentications.
4+
5+
Usually, a brand new Mobile ID SIM card must be activated just once on the MyMobileID Portal. With this Mobile ID activation process, the user can set his personal Mobile ID PIN (Set & Confirm PIN) and it will create the required signing key on the SIM card. After that, the SIM card is ready to be used for Mobile ID authentications.
6+
7+
Auto Activation is an optional feature that is disabled by default but can be enabled per Application Provider. If enabled, a Signature Request to a user with an inactive Mobile ID SIM (which means the user did not yet set his personal Mobile ID PIN) will invoke an implicit activation process during the on-going signature transaction.
8+
9+
So, the Auto Activation will achieve both a successful Mobile ID activation and a successful authentica-tion (Signature Response) at the same time! From now on, that user will be Mobile ID active.
10+
11+
From AP perspective, the user will just have a successful authentication and there is no difference whether the user was auto-activated (during the authentication transaction) or not.
12+
13+
Auto Activation feature can successfully prevent a fault sub-code 404 (this fault code means that the user did not yet activate his Mobile ID SIM card) which can happen when an AP attempts to do a Mobile ID authentication with a user that has an inactive Mobile ID SIM card.
14+
15+
## How to implement this feature
16+
To enable the Auto Activation feature for an Application Provider (AP), the AP must ensure that the user has accepted the Mobile ID specific terms & conditions prior to proceed with the auto activation steps.
17+
18+
An AP may use the Profile Query Extensions (see section 3.5) to know if a signature request to a user will invoke auto activation or not. However, an AP does not necessarily need to know that.
19+
20+
Please speak to your Swisscom contact if you wish to get this feature enabled for your AP account. Op-tionally we can also setup specific test SIM cards, which allows an AP to test this feature (because those test SIM cards will be configured to always trigger the auto activation).
21+
22+
23+
## User Perspective
24+
From a user perspective, the steps displayed on the mobile device look very similar, if you compare the signature process of an active Mobile ID SIM vs. the process of an inactive Mobile ID SIM.
25+
26+
Note that in case of a successful auto activation, the Mobile ID server sends a Text SMS to the user, to remind the user to create a Mobile ID recovery code [1].
27+
28+
**References**
29+
30+
1. Each time a user completes the Mobile ID activation process, she or he will receive a code that enables her or him to recover Mobile ID and maintain her or his existing pairings to service providers, if you lose your phone, change SIM cards or switch to an e-SIM card. See https://mobileid.ch/recovery
31+
32+
33+
34+

‎docs/reference-guide/best-practices.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Best Practices
2+
3+
The **Swisscom Mobile ID** GitHub repository provides various examples of Mobile ID client implementations.
4+
5+
The repository **[`mobileid-client-java`](https://github.com/SwisscomTrustServices/mobileid-client-java)** serves as the *main* Java‑based reference implementation for building **Mobile ID REST** and **SOAP** API clients.
6+
7+
This library is ideal for Java 8+ projects that require **secure authentication and authorization** using a mobile phone.
8+
It can be added as a dependency to your project and used in any scenario requiring access to the **Swisscom Mobile ID** service.
9+
10+
---
11+
12+
## MSS Signature
13+
14+
### Signature Request
15+
16+
When constructing an **MSS Signature** request, the following best‑practice guidelines should be followed:
17+
18+
1. **Define a unique `AP_TransID` (Transaction ID)**
19+
Each signature request must have a unique transaction identifier.
20+
21+
2. **Set the current time for `Instant` (with time zone)**
22+
The `Instant` parameter must include time zone information and must not deviate excessively from the Mobile ID Service’s current time; otherwise, a fault response with sub‑code **101** will be returned.
23+
- **Example:** `2020-01-01T12:00:00.000+01:00`
24+
- Must conform to the [W3C `xs:dateTime`](https://www.w3.org/TR/xmlschema-2/#dateTime) format.
25+
26+
3. **Ensure uniqueness across the triplet `(AP_ID, AP_TransID, Instant)`**
27+
The combination of these three fields must be unique for every transaction.
28+
Duplicate triplets are rejected.
29+
30+
4. **Specify `MSISDN` in international format**
31+
The user’s phone number must follow international (E.164) notation **without spaces**.
32+
A leading “+” is allowed but optional.
33+
- **Example:** `+41791234567`
34+
35+
5. **Set a valid `UserLang` value**
36+
The value must be one of the supported languages — **EN**, **DE**, **FR**, or **IT** — and must match the language used in the **DataToBeDisplayed** (`DTBD`) message.
37+
38+
6. **Define the `DataToBeDisplayed` (DTBD) message**
39+
The text shown on the user’s mobile device must comply with the following guidelines:
40+
- Encoded in **UTF‑8**.
41+
- Should include a **unique transaction reference** (e.g., timestamp, customer ID, contract ID).
42+
- **Length limits:**
43+
- Maximum **239 characters** if all characters are in the standard GSM DA character set.
44+
- If any character falls outside this set (e.g., the lowercase cedilla “ç”), the maximum length reduces to **119 characters**.
45+
- Keep the message as **short and user‑friendly** as possible.
46+
47+
**Example DTBD:**
48+
> `Bank ACME: Proceed with the login? (TXN‑3D5K)`
49+
50+
51+
### Signature Response
52+
53+
After receiving the **MSS Signature Response**, the client (Application Provider – AP) must perform proper response validation to ensure authenticity, integrity, and consistency with the original request.
54+
55+
The key validation aspects are as follows:
56+
57+
1. **Match Request and Response Identifiers**
58+
- Verify that the **`AP_TransID`** and **`MSISDN`** values in the response are identical to those sent in the original request.
59+
- Any mismatch should be treated as an invalid response and rejected.
60+
61+
2. **Validate the Mobile User’s X.509 Certificate**
62+
- Ensure the user certificate chains up to a **trusted root CA** contained in your local **TrustStore**.
63+
- The client should only trust certificates that link to a **trust anchor** matching the expected Swisscom Mobile ID CA.
64+
- Your **TrustStore** should only contain the **relevant root CA certificate** (see **Section 7**).
65+
66+
3. **Verify the Digital Signature**
67+
- Confirm that the received digital signature is **cryptographically valid**.
68+
- The **signed content** must correspond exactly to the **`DataToBeDisplayed (DTBD)`** text from the earlier signature request.
69+
- The client must be capable of validating both **RSA** and **ECDSA** signatures.
70+
71+
4. **(Optional) Validate the Mobile ID Serial Number**
72+
- For the **highest level of assurance** and a fully **strong two‑factor authentication** process, validate the **Mobile ID serial number** as described in **Section 4.2**.
73+
74+
5. **Implement Proper Fault and Status Handling**
75+
- Handle all **status** and **fault codes** using structured exception handling logic to ensure stable, predictable behavior of the client application.
76+
77+
---
78+
79+
**Important Note:**
80+
Certificate revocation checks are **not recommended**.
81+
Mobile ID user certificates are **never revoked** individually — the **Mobile ID service backend** manages account validity and state directly.
82+
83+
84+
### Signature Concurrency Control
85+
86+
This section describes the behavior of the **Mobile ID Service** when an **Application Provider (AP)** submits a new **MSS Signature** request while another signature transaction is already in progress for the **same MSISDN** and the **same authentication method**.
87+
88+
Concurrency handling depends on whether the request targets the **SIM** method or the **Mobile ID App** method.
89+
90+
---
91+
92+
##### • SIM Method Concurrency
93+
If both signature requests target the **SIM‑based authentication method**, and the first signature transaction is still **in progress**, the **second request** is **rejected** immediately.
94+
95+
- **Fault Code:** `406 / PB_SIGNATURE_PROCESS`
96+
- **Description:** The subscriber already has an active signature operation in process.
97+
- See **Section 6** for detailed fault code definitions.
98+
99+
---
100+
101+
##### • App Method Concurrency
102+
If both requests target the **Mobile ID App‑based authentication method**, the behavior is different:
103+
104+
- The **existing first signature transaction** is **canceled** automatically by the backend.
105+
- The **second signature request** is then displayed on the mobile device via the Mobile ID App.
106+
107+
- **Fault Code (cancellation of first transaction):** `401 / USER_CANCEL`
108+
- See **Section 6** for further information.
109+
110+
---
111+
112+
**Summary:**
113+
- **SIM method:** concurrency → second request **rejected**.
114+
- **App method:** concurrency → first request **canceled**, second request **processed**.
115+
116+
## Mobile ID Serial Number Validation
117+
118+
With an MSS Signature response, you will get signature data and the mobile user's X.509 certificate, which contains the public key required to validate the signature data.
119+
120+
That X.509 certificate's Subject Name (Distinguished Name) contains a unique Mobile ID serial number.
121+
122+
Example subject name with the serial number highlighted in pink:
123+
124+
cn=midcheptod58qe59:pn,serialnumber=midcheptod58qe59,pseudonym=midcheptod58qe59
125+
126+
127+
For highest level of assurance and a truly strong two-factor-authentication process, an AP should store this value at the first signature and then verify every subsequent signature response if that serial number value still matches.
128+
129+
If the value does not match anymore, it means that the user re-activated his account without a valid recovery option. In such case (serial number mismatch) the 2nd factor (knowledge/inherence) is not assured.
130+
131+
## Timeout Value
132+
133+
Use the reference values below to set an appropriate transaction timeout:
134+
135+
| MSS Operation | Transaction Timeout | Client Connection Timeout |
136+
|---------------|---------------------|---------------------------|
137+
| Synchronous MSS Signature | 80 seconds for Mobile ID SIM<br>40 seconds for Mobile ID App | 90 seconds<br>50 seconds |
138+
| Asynchronous MSS Signature | 80 seconds for Mobile ID SIM<br>40 seconds for Mobile ID App | 10 seconds |
139+
| MSS Status Query | - | 10 seconds |
140+
| MSS Receipt | - | 90 seconds |
141+
| MSS Profile Query | - | 10 seconds |
142+
143+
## Mobile ID FAQ
144+
145+
Please visit [https://mobileid.ch/en/faq](https://mobileid.ch/en/faq) for a list of frequently asked questions about Mobile ID
146+
147+
## Mobile ID Service Health Check
148+
149+
The recommended way to check the service health status is to send a synchronous MSS Signature request with the MSISDN value set to +41000000000 and DTBD set to Heartbeat.
150+
151+
The Mobile ID service health check is successful if a fault code 101/WRONG_PARAM with Detail value Illegal msisdn is returned, as shown in the example:
152+
153+
### SOAP/XML
154+
155+
```xml
156+
..
157+
<soapenv:Fault>
158+
<soapenv:Code>
159+
<soapenv:Value>soapenv:Sender</soapenv:Value>
160+
<soapenv:Subcode xmlns:mss="http://uri.etsi.org/TS102204/v1.1.2#"
161+
xmlns:fi="http://mss.ficom.fi/TS102204/v1.0.0#">
162+
<soapenv:Value>mss:_101</soapenv:Value>
163+
</soapenv:Subcode>
164+
</soapenv:Code>
165+
<soapenv:Reason>
166+
<soapenv:Text xml:lang="en">WRONG_PARAM</soapenv:Text>
167+
</soapenv:Reason>
168+
<soapenv:Detail>
169+
<ns1:detail xmlns:ns1="http://kiuru.methics.fi/mssp">Illegal msisdn</ns1:detail>
170+
</soapenv:Detail>
171+
</soapenv:Fault>
172+
..
173+
```
174+
175+
176+
### REST/JSON
177+
178+
```json
179+
..
180+
181+
{
182+
"Fault": {
183+
"Code": {
184+
"SubCode": {
185+
"Value": "_101",
186+
"ValueNs": "http://uri.etsi.org/TS102204/v1.1.2#"
187+
},
188+
"Value": "Sender",
189+
"ValueNs": "http://www.w3.org/2003/05/soap-envelope"
190+
},
191+
"Detail": "Illegal msisdn",
192+
"Reason": "WRONG_PARAM"
193+
}
194+
}
195+
196+
..
197+
```
198+
199+
200+
## Mobile ID Client Examples
201+
202+
The GitHub Repository at [https://github.com/MobileID-Strong-Authentication](https://github.com/MobileID-Strong-Authentication) contains different examples for a Mobile ID client.
203+
204+
The repo 'mobileid-client-java' is the main Java-based reference implementation for the Mobile ID REST and SOAP API client.
205+
206+
The library provided by this repository is for all clients that are developing Java-based projects that need secure authentication and authorization services using the mobile phone.
207+
208+
The library works with Java 8+ projects and can be added as a project dependency and used in any scenario that needs to access the Swisscom Mobile ID service.

0 commit comments

Comments
 (0)