Skip to content

Commit 3f00f5e

Browse files
author
Michael Troxler
committed
update reference-guide documentation
1 parent fd82b00 commit 3f00f5e

11 files changed

Lines changed: 268 additions & 82 deletions

‎docs/img/app-display-trans-approval.png‎

97.1 KB
Loading

‎docs/img/app-display-utf8.png‎

95.1 KB
Loading

‎docs/img/auth-flow-strong-flow.png‎

53.9 KB
Loading

‎docs/img/interconnection-backend.png‎

36.1 KB
Loading

‎docs/img/mobileid-login-accept.png‎

148 KB
Loading

‎docs/img/mobileid-login-pwd.png‎

135 KB
Loading

‎docs/img/mutual-authentication.png‎

40.5 KB
Loading

‎docs/img/synchronous-mss-signature.png‎

38.9 KB
Loading

‎docs/reference-guide/app-provider-client-integration.md‎

Lines changed: 89 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,105 @@
11
# Application Provider Client Integration
22

3-
This chapter describes how an **Application Provider (AP)** integrates its backend with the **Swisscom Mobile ID signature service**.
4-
It covers the necessary preconditions, endpoint configuration, and use of **mutual TLS authentication**.
5-
6-
---
3+
This chapter describes how an **Application Provider (AP)** integrates its backend with the **Swisscom Mobile ID signature service**. It covers the necessary preconditions, endpoint configuration, and use of **mutual TLS authentication**.
74

85
## Preconditions
96

10-
Before using the Swisscom Mobile ID Web Service, the following setup steps are required:
11-
12-
1. The Mobile ID customer (your organization) has a valid agreement with Swisscom.
13-
Under this agreement:
14-
15-
- **Connectivity** between your AP and the Mobile ID platform is established
16-
(either over the Internet or via Swisscom LAN‑I service).
17-
- The AP’s **public source IP address or range** must be **whitelisted** in the Swisscom firewall.
18-
- The customer must deliver an **X.509 client certificate** to Swisscom.
19-
*(Creation is described in Chapter 8*
7+
Before using the **Swisscom Mobile ID** web service, some initial provisioning steps are required.
208

21-
2. Swisscom provides the customer with:
22-
- an **AP_ID (Application Provider Identifier)**, and
23-
- a **DTBD Prefix** value.
9+
1. **The Mobile ID customer (your company) has an agreement with Swisscom:**
10+
- **Connectivity** (Internet or LAN‑I) between the **AP** and **Mobile ID** has been established.
11+
- The AP’s public source IP address (or range) must be whitelisted in the **Swisscom Firewall**.
12+
- The customer has delivered the **X.509 client certificate** to Swisscom (see Create X509 Client Certificates).
2413

25-
The **DTBD Prefix** is an AP‑specific keyword that must appear as a **prefix** in every Mobile ID message shown to the end‑user.
26-
It identifies the requesting application on the handset display.
14+
2. **The Mobile ID customer receives from Swisscom:**
15+
- An **AP_ID** (Application Provider Identifier) value.
16+
- A **DataToBeDisplayed (DTBD) Prefix** value:
17+
- The DTBD Prefix is an AP‑specific keyword that must be included as a prefix in every Mobile ID request text message sent to a Mobile ID user (the message displayed on the user’s mobile phone).
18+
- **Example:** `"Bank ACME: "`
2719

2820
---
2921

3022
## Endpoint Address
3123

32-
The Mobile ID Web Service is accessible via both **SOAP** and **REST** interfaces.
33-
Use whichever best matches your platform integration strategy.
24+
The Swisscom Mobile ID web service is accessible through LAN-I or Internet. If not otherwise specified use the following default access details.
25+
26+
27+
| Environment | URL |
28+
|-------------------|----------------------------------------|
29+
| **Internet** | [https://mobileid.swisscom.com](https://mobileid.swisscom.com) |
30+
| **Swisscom LAN‑I** | [https://195.65.233.218](https://195.65.233.218) |
31+
32+
### Overview Access
33+
34+
![interconnection-backend](/img/interconnection-backend.png)
35+
36+
::: info
37+
For accessing the service endpoints the Mobile ID customer can choose between SOAP or RESTful endpoints.
38+
:::
3439

3540
### **SOAP Endpoint**
3641

37-
A dedicated HTTPS endpoint implementing ETSI TS 102 204 for Mobile ID Signatures.
42+
A description of this interface is available as a **WSDL** file on GitHub: [mobileid.yaml](https://github.com/MobileID-Strong-Authentication/mobileid-api/blob/main/soap/mobileid.wsdl)
43+
44+
#### Endpoints
45+
46+
| Endpoint URL | Description | Reference Section |
47+
|---------------|--------------|-------------------|
48+
| `<Base‑URL>/soap/services/MSS_SignaturePort` | **MSS Signature** | Section 3.2 |
49+
| `<Base‑URL>/soap/services/MSS_StatusQueryPort` | **MSS Status Query** | Section 0 |
50+
| `<Base‑URL>/soap/services/MSS_ReceiptPort` | **MSS Receipt** | Section 3.4 |
51+
| `<Base‑URL>/soap/services/MSS_ProfilePort` | **MSS Profile Query** | Section 3.5 |
52+
53+
### **REST Endpoint**
54+
A description of this interface is available as a **YAML** file on GitHub: [mobileid.yaml](https://github.com/MobileID-Strong-Authentication/mobileid-api/blob/main/rest/mobileid.yaml)
55+
56+
#### Endpoints
57+
58+
| Endpoint URL | Description | Reference Section |
59+
|---------------|--------------|-------------------|
60+
| `<Base‑URL>/rest/service/sign` | **MSS Signature** | Section 3.2 |
61+
| `<Base‑URL>/rest/service/status` | **MSS Status Query** | Section 0 |
62+
| `<Base‑URL>/rest/service/receipt` | **MSS Receipt** | Section 3.4 |
63+
| `<Base‑URL>/rest/service/profile` | **MSS Profile Query** | Section 3.5 |
64+
65+
66+
## Mutual Authentication
67+
68+
A certificate-based mutual authentication when accessing the Mobile ID web service is highly recommended. When using certificate-based mutual authentication, the following actions occur:
69+
70+
![mutual-authentication](/img/mutual-authentication.png)
71+
72+
73+
1. The **client Application Provider (AP)** requests access to a protected resource on the **Mobile ID (MID)** server.
74+
2. The **MID web server** presents its **server certificate** to the client AP.
75+
3. The **client AP** verifies the MID **server certificate**.
76+
4. If verification is successful, the **client AP** sends its **client certificate** to the MID server.
77+
5. The **MID server** verifies the **AP client credentials**.
78+
6. If verification succeeds, the **MID server** grants access to the protected resource requested by the client AP.
79+
80+
81+
### Important Guidelines for Certificate-Based Mutual Authentication
82+
83+
- The client must send **only its end‑entity certificate**.
84+
- Authentication on the MID side does not consider validation of a full client certificate chain or any restrictions on the root CA.
85+
- Authentication is **denied** if the client sends a bag with the full certificate chain.
86+
87+
- The **Enhanced Key Usage** value of client certificates must include **Client Authentication** (`1.3.6.1.5.5.7.3.2`).
88+
- See **X509 Client Certificates** for examples of creating self‑signed certificates.
89+
90+
- All requests to the **Mobile ID service** must originate **only** from servers that you control.
91+
- Never send requests directly from client‑side code such as **mobile apps** or **JavaScript**, as this may compromise your credentials.
92+
93+
- To validate the **chain of trust** for the Mobile ID server certificate:
94+
- Add the **SwissSign Gold CA – G2** root certificate to your client **TrustStore**.
95+
- The intermediate CAs are returned dynamically by the MID server and may change.
96+
- Refer to **Section tbd** for more details.
97+
98+
::: info
99+
Get the root certificate from https://www.swisssign.com/en/support/faq.html
100+
:::
101+
102+
103+
104+
38105

39-
```text
40-
https://mobileid.swisscom.com/soap/services/MSS_Signature

‎docs/reference-guide/introduction.md‎

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -43,71 +43,106 @@ Authentication in Mobile ID is based on a secure hardware token which can be e
4343
- a **Mobile ID‑compliant SIM or eSIM**, or
4444
- a **Mobile ID App** running on a smartphone.
4545

46-
A single user account may have both methods enabled.
47-
The **Application Provider (AP)** can select and allow one or both methods for authentication.
46+
Therefore, a user account could have either the (e)SIM method, the App method or even both methods activated at the same time. However, the **Application Provider (AP)** may select the preferred method and allow both methods or just either one.
4847

4948
---
5049

51-
### **Mobile ID (e‑)SIM Method**
50+
### **Mobile ID SIM - Method**
5251

53-
The **SIM method** uses the **SIM Toolkit (STK)** application residing on the SIM card (or eSIM profile).
52+
An Application Provider (AP) can request SIM Toolkit (STK) based authentication, hereinafter referred as "SIM method". To utilize the SIM method, the user must have a Mobile ID compliant SIM card or eSIM. Data exchange between the Mobile ID server and the STK application is done with SMS messages using data packets (PDUs), not visible to the end-user. The Mobile ID SIM Toolkit application runs on the SIM card environment and is compliant with all mobile devices.
5453

5554

55+
![mobileid-login-accept](/img/mobileid-login-accept.png)
5656

57-
The STK app communicates securely with the Mobile ID server by **encrypted SMS PDUs**, invisible to the user.
5857

5958
#### **Key Advantages**
6059

6160
- **Strong Two‑Factor Authentication**
62-
- 1️⃣ *Possession Factor*: Physical SIM/eSIM
63-
- 2️⃣ *Knowledge Factor*: Personal Mobile ID PIN
61+
- **1st Factor:** Physical SIM/eSIM (Possession Factor)
62+
- **2nd Factor:** Personal Mobile ID PIN (Knowledge Factor)
6463

6564
- **High Level of Security**
6665
- Tamper‑proof secure hardware (EAL5+ and ITSEC E3 certified)
6766
- Authentication via a separate encrypted channel
6867

6968
- **Pre‑installed** STK App on the SIM/eSIM profile
7069

71-
- Supported by most **Swiss Mobile Network Operators**
72-
*(Swisscom, Sunrise, Salt, UPC)*
70+
- Supported by most **Swiss Mobile Network Operators** *(Swisscom, Sunrise, Salt)*
7371

7472
---
7573

76-
### **Mobile ID App Method**
77-
78-
The **App method** allows authentication using the **Mobile ID App** installed on an Android or iOS device.
79-
74+
### **Mobile ID App - Method**
8075

76+
An Application Provider (AP) can request mobile app based authentication, hereinafter referred as "App method". To utilize the App method, the user must have the Mobile ID App installed on a compliant Android or iOS-based smartphone. The app can be downloaded from Google Play Store and Apple App Store.
8177

8278
#### **Activation Options**
8379

80+
The Mobile ID App activation can be done within the mobile app (in-app enrolment) or through the selfcare portal (in latter case, the app must scan a QR code displayed on www.mobileid.ch).
81+
8482
1. **In‑App Enrolment**
8583
The user activates Mobile ID directly within the app.
8684

8785
2. **Self‑Care Portal Activation**
8886
Activation via [https://www.mobileid.ch](https://www.mobileid.ch),
8987
where the app scans a QR code displayed on the site.
9088

91-
The App can display plain UTF‑8 text for user confirmation — the so‑called
92-
**DTBD (Classic View)**.
89+
#### **Display Options**
90+
91+
The App can display a plain UTF-8 string as a single text line. This is known as the
92+
DTBD (DataToBeDisplayed) Classic View.
93+
94+
![app-display-utf8](/img/app-display-utf8.png)
95+
9396

94-
---
9597

96-
### **High‑Level Authentication Flow**
98+
The App also supports Transaction Approval Style, which enhances readability by displaying
99+
a title (type-field) and one or more key-value rows.
97100

101+
![app-display-trans-approval](/img/app-display-trans-approval.png)
98102

99103

100-
1. The Application Provider (AP) initiates an authentication or signature request.
101-
2. The Mobile ID platform sends an authentication challenge to the user’s device (SIM or App).
102-
3. The user verifies the **DTBD message** displayed and confirms using their **Mobile ID PIN** or biometrics.
103-
4. The device returns the signed response with the user’s **X.509 certificate**.
104-
5. The AP backend validates both signature and certificate chain via the **Swisscom Mobile ID API**.
104+
#### App Method Key Advantages
105+
106+
- **Strong Two-Factor Authentication**
107+
- **1st Factor:** Smartphone (Possession Factor)
108+
- **2nd Factor:** Passcode (Knowledge Factor) or Biometry (Inherence Factor)
109+
110+
- **High Level of Security**
111+
- Authentication through dedicated mobile application (authentication app)
112+
- Fast and secure (encrypted) communication
113+
114+
- **Availability**
115+
- The app is published and available in several countries of the European Union (EU)
116+
105117

106118
---
107119

108-
### **Security Highlights**
120+
### **Authentication Flow**
121+
122+
Before going into more technical details, let’s have a short look at the main scenario.
123+
124+
**Strong Authentication**:
125+
The end-user wants to access a corporate application protected by Mobile ID strong authentication.
126+
127+
![auth-flow-strong-flow](/img/auth-flow-strong-flow.png)
128+
129+
130+
#### Main Steps Performed by the End-User and the Mobile Signature Service
131+
132+
1. The end-user uses any application relying on **Mobile ID** for authentication.
133+
- The application sends a mobile signature request through the dedicated web interface (of the **AP**), including the personal **MSISDN** as an input parameter to log in.
134+
135+
2. The **AP** receives the end-user request, forms the contents to be signed (in accordance with the **ETSI TS 102 204** standard), and forwards the request to the **MID** service.
136+
137+
3. The **MID** platform receives the signature request and validates the **AP** in accordance with the service agreement.
138+
139+
4. The **MID** platform ensures that the end-user signature request is allowed and forwards the signature request to the end-user’s mobile phone.
140+
141+
5. The end-user receives a message on their mobile phone to sign the mobile signature request.
142+
- The end-user confirms the authentication request either by providing the **Mobile ID PIN** (SIM method) or **Passcode/Biometry** (App method).
143+
144+
After the **AP** has received a valid response, the end-user is granted access to the corporate application.
145+
146+
147+
---
109148

110-
- Meets **ETSI and Swiss regulatory requirements**.
111-
- End‑to‑end encryption between AP, MSSP, and user device.
112-
- Compatible with both **(e)SIM** and **App** deployment methods.
113-
- Compliant with **two‑factor authentication frameworks** and online signature standards.

0 commit comments

Comments
 (0)