#### **Key Advantages**
- **Strong Two-Factor Authentication**
- **1st Factor:** Physical SIM/eSIM (Possession Factor)
- **2nd Factor:** Personal Mobile ID PIN (Knowledge Factor)
- **High Level of Security**
- Tamper-proof secure hardware ([EAL5+](https://www.commoncriteriaportal.org/ccra/) and ITSEC E3 certified)
- Authentication via a separate encrypted channel
- **Pre-installed** STK App on the SIM/eSIM profile
- Supported by most **Swiss Mobile Network Operators** *(Swisscom, Sunrise, Salt)*
### **Mobile ID App - Method**
An Application Provider (AP) can request mobile app based authentication, hereinafter referred to 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 the Google Play Store and Apple App Store.
#### **Activation Options**
The Mobile ID App activation can be done within the mobile app (in-app enrolment) or through the self-care portal (in the latter case, the app must scan a QR code displayed on www.mobileid.ch).
1. **In-App Enrolment**
The user activates Mobile ID directly within the app.
2. **Self-Care Portal Activation**
Activation via [https://www.mobileid.ch](https://www.mobileid.ch),
where the app scans a QR code displayed on the site.
#### **Display Options**
The App can display a plain UTF-8 string as a single text line. This is known as the
DTBD (DataToBeDisplayed) Classic View.
The App also supports Transaction Approval Style, which enhances readability by displaying
a title (type-field) and one or more key-value rows.
#### App Method Key Advantages
- **Strong Two-Factor Authentication**
- **1st Factor:** Smartphone (Possession Factor)
- **2nd Factor:** Passcode (Knowledge Factor) or Biometry (Inherence Factor)
- **High Level of Security**
- Authentication through dedicated mobile application (authentication app)
- Fast and secure (encrypted) communication
- **Availability**
- The app is published and available in several countries of the European Union (EU)
### **Authentication Flow**
Before going into more technical details, let’s have a short look at the main scenario.
**Strong Authentication**:
The end-user wants to access a corporate application protected by Mobile ID strong authentication.
#### Main Steps Performed by the End-User and the Mobile Signature Service
1. The end-user uses any application relying on **Mobile ID** for authentication.
- 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.
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.
3. The **MID** platform receives the signature request and validates the **AP** in accordance with the service agreement.
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.
5. The end-user receives a message on their mobile phone to sign the mobile signature request.
- The end-user confirms the authentication request either by providing the **Mobile ID PIN** (SIM method) or **Passcode/Biometry** (App method).
After the **AP** has received a valid response, the end-user is granted access to the corporate application.
---
## REST API Integration Steps
Source: https://docs.mobileid.ch/rest-api-guide/app-provider-client-integration.html
# Integration Steps
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.
## Preconditions
Before using the Swisscom Mobile ID web service, some initial provisioning steps are required.
1. **The Mobile ID customer (your company) has an agreement with Swisscom:**
- **Connectivity** (Internet or [EC](https://www.swisscom.ch/en/business/enterprise/offer/wireline/enterprise-connect.html)) between the **AP** and **Mobile ID** has been established.
- The customer has delivered the **X.509 client certificate** to Swisscom (see [Create X509 Client Certificates](/rest-api-guide/create-client-certs.md)).
::: warning Firewall Whitelisting
The AP’s public source IP address (or range) must be whitelisted in the **Swisscom Firewall**. Contact Swisscom to request whitelisting.
:::
2. **The Mobile ID customer receives from Swisscom:**
- An **AP_ID** (Application Provider Identifier) value.
- A **DataToBeDisplayed (DTBD) Prefix** value:
- 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).
- **Example:** `"Bank ACME: "`
## Endpoint Address
The Swisscom Mobile ID web service is accessible through EC ([Enterprise Connect](https://www.swisscom.ch/en/business/enterprise/offer/wireline/enterprise-connect.html)) or the Internet. If not otherwise specified, use the following default access details.
| Environment | URL |
|-------------------|----------------------------------------|
| **Internet** | [https://mobileid.swisscom.com](https://mobileid.swisscom.com) |
| **Swisscom EC** | [https://195.65.233.218](https://195.65.233.218) |
### Overview Access
```mermaid
flowchart LR
subgraph CE[Customer Environment]
direction TB
AP[AP_IDBy default, this signature profile is mapped to `http://mid.swisscom.ch/STK-LoA4`. | Any AP is authorized. | | `http://mid.swisscom.ch/Any-LoA4` | Mobile ID backend will automatically choose **SIM** or **App** authentication based on the user’s configured methods:
– The **SIM** method is always preferred.
– The **App** method is only selected if it is the *only* active method for that user.
The response will indicate which authentication method was chosen. | By default, an AP is **not authorized** to use this profile.
Please contact **Swisscom** if you intend to use it. | | `http://mid.swisscom.ch/STK-LoA4` | Forces **SIM authentication** method. | By default, an AP is **not authorized** to use this profile.
Please ask **Swisscom** if you intend to use it. | | `http://mid.swisscom.ch/Device-LoA4` | Forces **App authentication** method. | By default, an AP is **not authorized** to use this profile.
Please ask **Swisscom** if you intend to use it. | | `http://mid.swisscom.ch/Any-Geofencing-LoA4` | Mobile ID backend will choose **SIM** or **App** authentication based on both the user’s authentication and **geo-location** capabilities:
– **SIM** method is preferred but only if the SIM has geo-location capabilities (Swisscom SIM only).
– **App** method is selected if it is the only active method for that user, or if the user’s SIM lacks geo-location capabilities. | By default, an AP is **not authorized** to use this profile.
The AP must have **Geofencing Additional Service** permission.
Please ask **Swisscom** if you intend to use it. | ::: warning Note If an AP is not authorized to use a specific signature profile, the request is rejected with the fault response. ::: ### User Scenario Examples (Signature Profile Handling) The following examples demonstrate how the Mobile ID backend responds to different signature profile values, depending on the user's active authentication methods (SIM, App, or both). The table below illustrates several example user scenarios and how the **MSSP** (Mobile ID backend) responds to a given **MSS Signature** request, depending on the user’s authentication capabilities and the selected **SignatureProfile** value. Please note that these examples are **illustrative**, not exhaustive. #### AP configuration example - The AP is authorized to use all signature profiles. - The AP has a signature profile mapping configured so that an incoming signature profile `http://mid.swisscom.ch/MID/v1/AuthProfile1` is mapped internally to `http://mid.swisscom.ch/Any-LoA4`. - These examples may not apply to every AP configuration; some APs may not be authorized to use all signature profiles, and others may not have a mapping configured. #### MSSP Response Logic per Scenario | MID User | SIM | App | Request’s Signature Profile | Response’s Signature Profile | |-----------|-----|-----|-----------------------------|------------------------------| | *(No active SIM / App)* | ✗ | ✗ | `http://mid.swisscom.ch/MID/v1/AuthProfile1` | n/a *(Fault 105 / UNKNOWN_CLIENT)* | | | | | `http://mid.swisscom.ch/Any-LoA4` | n/a *(Fault 105 / UNKNOWN_CLIENT)* | | | | | `http://mid.swisscom.ch/STK-LoA4` | n/a *(Fault 105 / UNKNOWN_CLIENT)* | | | | | `http://mid.swisscom.ch/Device-LoA4` | n/a *(Fault 105 / UNKNOWN_CLIENT)* | | **Active SIM only** | ✓ | ✗ | `http://mid.swisscom.ch/MID/v1/AuthProfile1` | `http://mid.swisscom.ch/STK-LoA4` | | | | | `http://mid.swisscom.ch/Any-LoA4` | `http://mid.swisscom.ch/STK-LoA4` | | | | | `http://mid.swisscom.ch/STK-LoA4` | `http://mid.swisscom.ch/STK-LoA4` | | | | | `http://mid.swisscom.ch/Device-LoA4` | n/a *(Fault 109 / UNSUPPORTED_PROFILE)* | | **Active App only** | ✗ | ✓ | `http://mid.swisscom.ch/MID/v1/AuthProfile1` | `http://mid.swisscom.ch/Device-LoA4` | | | | | `http://mid.swisscom.ch/Any-LoA4` | `http://mid.swisscom.ch/Device-LoA4` | | | | | `http://mid.swisscom.ch/STK-LoA4` | n/a *(Fault 109 / UNSUPPORTED_PROFILE)* | | | | | `http://mid.swisscom.ch/Device-LoA4` | `http://mid.swisscom.ch/Device-LoA4` | | **Active SIM and App** | ✓ | ✓ | `http://mid.swisscom.ch/MID/v1/AuthProfile1` | `http://mid.swisscom.ch/STK-LoA4` | | | | | `http://mid.swisscom.ch/Any-LoA4` | `http://mid.swisscom.ch/STK-LoA4` | | | | | `http://mid.swisscom.ch/STK-LoA4` | `http://mid.swisscom.ch/STK-LoA4` | | | | | `http://mid.swisscom.ch/Device-LoA4` | `http://mid.swisscom.ch/Device-LoA4` | ::: info Note An AP can use the **MSS Profile Query** request (see **[MSS Profile Query](/rest-api-guide/mobile-id-api#mss-profile-query)**) to determine a user’s capabilities. For example, to check whether a particular user supports **SIM** and/or **App**-based authentication before sending the signature request. ::: ### Signature Messaging Mode The [ETSI TS 102 204](https://www.etsi.org/deliver/etsi_ts/102200_102299/102204/) standard has defined the MSS Signature and Swisscom supports both synchronous and asynchronous (client-server) modes. The MSS_Signature method is used to submit the mobile signature request message (MSS_SignatureReq). The result is provided within the signature response message (MSS_SignatureResp). The Mobile ID customer (AP) can decide to call either synchronous or asynchronous signature requests. There are different aspects to consider: - With the synchronous mode, the signature response is immediately processed by the AP after it has been made available by the Mobile ID Service, making the overall authentication transaction faster. If an Application Provider intends to invoke many signature transactions of different users in parallel, it may require more memory because each thread is waiting for its completion. - With the asynchronous client-server mode, the Application Provider needs to implement a polling mechanism (query the transaction status every x seconds until the signature has been made available by the Mobile ID Service). ### Synchronous MSS Signature The following steps describe a typical synchronous (MessagingMode="synch") Mobile ID authentication transaction:  1. **End-User Action** The end-user uses an application that initiates an authentication request. 2. **Application Provider (AP) Request** The AP receives the authentication request and sends an `MSS_SignatureReq` message with parameter `MessagingMode="synch"` to the MSSP (Mobile ID backend). 3. **AP Credential Validation** The **Mobile ID backend (MSSP)** validates the **AP’s credentials** and verifies its authorization. 4. **Signature Request to User Device** The **Mobile ID backend** sends a signature request to the mobile device — either to the **SIM (STK applet)** or to the **Mobile ID App**, depending on the user’s configured method. 5. **User Authentication & Digital Signature** The Mobile ID application on the mobile device prompts the user to enter their Mobile ID secret (PIN, passcode, or biometric factor). - The user confirms with the correct secret. - The mobile application digitally signs the authentication payload. - The resulting digital signature is returned to the Mobile ID backend (MSSP). 6. **Signature Response Received** The MSSP receives the signature response and processes it. 7. **Response to Application Provider** The **Mobile ID backend** returns a **complete response** to the **AP**, containing: - The **digital signature**, and - The **certificate** that includes the end-user’s public key. 8. **Access Decision by the AP** Based on the Mobile ID response, the AP may grant or deny access to the end-user, depending on the authentication outcome. #### Synchronous MSS Signature Request ::: code-group ```json [REST/json] { "MSS_SignatureReq": { "AP_Info": { "AP_ID": "yourAP_ID", "AP_PWD": "not-needed", "AP_TransID": "REF0101120000", "Instant": "2015-01-01T12:00:00.000+01:00" }, "AdditionalServices": [ { "Description": "http://mss.ficom.fi/TS102204/v1.0.0#userLang", "UserLang": { "Value": "LANGUAGE" } } ], "DataToBeSigned": { "Data": "TEXT_TO_BE_SIGNED", "Encoding": "UTF-8", "MimeType": "text/plain" }, "MSSP_Info": { "MSSP_ID": { "URI": "http://mid.swisscom.ch/" } }, "MajorVersion": "1", "MessagingMode": "synch", "MinorVersion": "2", "MobileUser": { "MSISDN": "MOBILE_NUMBER" }, "SignatureProfile": "SIGNATURE_PROFILE", "TimeOut": "80" } } ``` ```xml [SOAP/xml]
40 seconds for Mobile ID App | 90 seconds
50 seconds | | Asynchronous MSS Signature | 80 seconds for Mobile ID SIM
40 seconds for Mobile ID App | 10 seconds | | MSS Status Query | - | 10 seconds | | MSS Receipt | - | 90 seconds | | MSS Profile Query | - | 10 seconds | ::: ## Mobile ID FAQ Please visit [https://mobileid.ch/en/faq](https://mobileid.ch/en/faq) for a list of frequently asked questions about Mobile ID ## Mobile ID Service Health Check 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. 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: ### SOAP/XML ```xml ..
(Browser, App) participant RP as Relying Party
company.ch participant AuthZ as Mobile ID (OP)
Authorization Endpoint participant Tok as Mobile ID (OP)
Token Endpoint participant UI as Mobile ID (OP)
UserInfo Endpoint rect rgb(240, 248, 255) Note over EU, AuthZ: (A) EU->>UA: User clicks sign-in button at https://company.ch to request access to protected resource UA->>RP: Note right of RP: optional parameters are
login_hint, ui_locales,
dtbd, acr_values RP->>AuthZ: AuthZ->>UA: Redirect to https://m.mobileid.ch end rect rgb(240, 255, 240) Note over EU, AuthZ: (B) UA->>AuthZ: Authentication request : client_id, redirect_uri, scope AuthZ->>AuthZ: Validate client AuthZ->>UA: Return sign-in page of https://m.mobileid.ch UA->>AuthZ: User starts sign-in at https://m.mobileid.ch AuthZ->>AuthZ: Start Mobile ID authentication & authorization
incl. account recovery, if needed AuthZ->>EU: Mobile ID authentication request to confirm sign in to protected resource Note left of EU: Authenticate with
Mobile ID EU->>AuthZ: Mobile ID authentication response AuthZ->>AuthZ: Cache authentication data temporarily EU->>AuthZ: User grants access to user information (authorization step) end rect rgb(255, 248, 240) Note over UA, AuthZ: (C) AuthZ->>UA: Redirect to https://company.ch + authorization-code (short lived) UA->>RP: Authorization-code end rect rgb(240, 240, 255) Note over RP, Tok: (D) RP->>Tok: Request access token and ID token using authorization-code Tok->>Tok: Validate authorization-code end rect rgb(255, 240, 255) Note over RP, Tok: (E) Tok->>RP: access token & ID token returned (short-lived) end rect rgb(255, 255, 240) Note over RP, UI: (F) Optionally to retrieve extra user info RP->>UI: request user claims using ID token UI->>UI: Validate token UI->>RP: claims returned (phone number, location, etc.) RP->>RP: Validate extra user info end rect rgb(245, 245, 245) Note over EU, RP: (G) RP->>UA: Allow or deny access based on access token and optional user info UA->>EU: User is signed in end ``` 1. An **End-User** requests access to a protected resource of the Relying Party. For example, the End-User clicks on a sign-in button or launches an app. The Relying Party redirects the User-Agent to the Mobile ID Authorization Endpoint at `https://m.mobileid.ch`. 2. The Mobile ID Authorization Server **authenticates** the End-User (using an appropriate Mobile ID authentication method) and establishes whether the End-User grants or denies the Relying Party Client's access request, including access to extra user information that might have been requested in the scope of the authentication request sent by the Relying Party. 3. The Mobile ID Authorization Server **redirects** the User-Agent back to the Relying Party's web site or application using the redirection URI provided earlier in step 1. The redirection URI includes an **Authorization code** that is valid for a few minutes. 4. Relying Party requests an **Access Token** from the Mobile ID Token Endpoint by including the Authorization code received in the previous step. When making the request, the Relying Party authenticates with the Mobile ID server. The client includes the redirection URI used to obtain the authorization code for verification. 5. The Mobile ID server authenticates the client, validates the authorization code, and ensures that the redirection URI received matches the URI used to redirect the client in step 3. On success, the Mobile ID server will return a JSON object with the **ID Token** and an **Access Token**, and an optional **Refresh Token**. 6. **Optional:** Relying Party requests additional, consented user information (claims). The user info endpoint returns previously consented user profile information to the client. A valid access token is required for that. 7. Relying Party grants or denies access to the requested service and the user is logged in. ## Refresh Token Because Access Tokens are always short-lived (see [Tokens](/oidc-integration-guide/getting-started#tokens)), a Relying Party may want to refresh the Access Token using their long-lived Refresh Token. To refresh an Access Token, the Client must always authenticate at the Token Endpoint. The Relying Party should always validate the Refresh Response.  ::: warning A Relying Party must be authorized to use a Refresh Token. ::: --- ## OIDC Getting Started Source: https://docs.mobileid.ch/oidc-integration-guide/getting-started.html # Getting Started Before you can integrate and use Mobile ID OpenID Connect sign-in, the client on-boarding process must have been completed by Swisscom. For the technical on-boarding, you will be asked to provide Swisscom with the following information: | What | Quick Description | Ref. | |------|--------------------|------| | **Client Display Name** | Your client's name, which is displayed by the authorization server.
Example value: `iDemo Online Shop` | | | **Redirect URI(s)** | Redirection URI(s) to which the response will be sent. Note that TLS (https) is always required and the localhost URI is not allowed.
Example value:
`https://app01.idemo-company.ch/oauth2/authresp`
`https://app02.idemo-company.ch/oauth2/authresp` | [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) | | **Default ACR** | Your default ACR. Must be a value that is available for your selected Mobile ID contract.
Example value: `mid_al3_any` | [Section Auth Code Request](/oidc-integration-guide/getting-started#authorization-code-request) | | **Client Auth Mode** | Your client's authentication method, either basic or post.
Example value: `client_secret_post` | [Section Access Token Request](/oidc-integration-guide/getting-started#access-token-request) | | **Always Prompt For Consent** | The Mobile ID server default behavior is to skip the consent step, provided such is already recorded for the given end-user and client.
Default: `false` | | | **MFA Number Matching** | Enable MFA number matching feature for Mobile ID SIM and Mobile ID App authentication.
When a user responds to an MFA notification using Mobile ID SIM or Mobile ID App, they'll be presented with a number on their mobile. They need to select that number in the sign-in prompt to complete the approval.
Default: `false` | [Video](https://youtu.be/4ACfK_kByKY) | | **LDAP Settings** | Optional. Mobile ID server can connect to an LDAP(S) to validate user credentials and/or retrieve user attributes from the LDAP, such as:
- MFA mobile number attribute
- Mobile ID Serialnumber attribute (required for ACR mid_al4)
- User password attribute | | | **CNAME Record** | Optional. Mobile ID server can use a custom domain instead of the default m.mobileid.ch. Custom Domains are only relevant if prompt=login is used. We will need your record name (e.g. mobileid.acme.com) that routes the traffic to m.mobileid.ch. | | You will get a unique OIDC client identifier and client secret from Swisscom. If you did not receive your client credentials, it means that your on-boarding process is not finished yet. ::: tip Check the state with your commercial contact or via **Backoffice.Security@swisscom.com**. ::: ## Endpoint URIs A default Mobile ID OpenID Provider configuration is published on the OIDC discovery endpoint, which allows a client to discover the OAuth 2.0 and OpenID Connect endpoints, capabilities, supported cryptographic algorithms and features. ::: info It is recommended to host a local copy of the discovery document when your application relies on constant availability of this endpoint data. ::: | Endpoint | URL | |-----------|-----| | Discovery | https://openid.mobileid.ch/.well-known/openid-configuration | Additional Endpoint URIs: | Endpoint | URL | |-----------|-----| | Authorization | https://m.mobileid.ch/oidc/authorize | | Token | https://openid.mobileid.ch/token | | User Info | https://openid.mobileid.ch/userinfo | | Pushed Authorization Requests | https://openid.mobileid.ch/par | ## Authorization Code Request The authorization code can be obtained by performing a simple HTTP GET request towards the Authorization endpoint of the Mobile ID OP. The client secret is not involved yet. | Endpoint | URL | |-----------|-----| | Authorization | https://m.mobileid.ch/oidc/authorize | The Relying Party may trigger the authorization code flow by calling the authorization link (including required request parameters), for example: ```html MobileID-sign-in-button ``` ::: warning For data privacy reasons, it is highly recommended that the Relying Party does not fill in the HTTP referrer header. Typically, the referrer header is populated with the address of the page where the request originated. The HTML hyperlinks should have the `rel` attribute set to `noreferrer`, as shown in the example above. ::: A button could look like this example:
A click on the button will redirect the user to the mobileid.ch domain, where they can complete the authorization code flow. In the example screenshots below, the user enters the phone number, authenticates with the Mobile ID App and consents to the user information (phone number, current location) that was requested by the Relying Party "iDemo App". Finally, the user is redirected back to the Relying Party's domain.
The following request query string parameters are supported:
| Parameter | Value | Remarks |
|-----------|-------|---------|
| `scope` | MUST contain the value `openid` | Optionally, the client may request additional scopes as specified in [Scopes and Claims](/oidc-integration-guide/getting-started#scopes-and-claims) |
| `response_type` | MUST be the value `code` | |
| `client_id` | MUST be your client ID | |
| `redirect_uri` | MUST be (one of) your redirect URI(s) | |
| `state` | MUST be an opaque value | Used to maintain state between the request and the callback |
| `nonce` | MUST be a nonce value | |
| `acr_values` | CAN be set to overwrite the client's default ACR | Authentication Level (AL) required by the client (see [ACR](/oidc-integration-guide/getting-started#authentication-context-class-reference-acr)) |
| `response_mode` | SHALL NOT be used | |
| `display` | SHALL NOT be used | |
| `prompt` | CAN be set to `login` | |
| `max_age` | SHALL NOT be used | |
| `ui_locales` | CAN be set to provide the user's preferred language | Supported values are `en`, `de`, `fr` and `it` |
| `id_token_hint` | SHALL NOT be used | |
| `claims` | SHALL NOT be used | |
| `login_hint` | CAN be set to provide a login hint to the authorization server about the end-user's phone number(s) or LDAP username. Must be in a JSON format. | See [Login Hint Examples](/oidc-integration-guide/getting-started#login-hint-examples) below. |
| `dtbd` | CAN be set to overwrite the default authentication message displayed to the end-user if the authentication method is either Mobile ID SIM or Mobile ID App. | See [DTBD Parameter](/oidc-integration-guide/getting-started#dtbd-parameter) below. |
#### Login Hint Examples
Standard login hints:
```json
{"enableManualInput": true, "hints": [{"msisdn":"+41765XXXXXX"}]}
{"enableManualInput": true, "hints": [{"msisdn":"+41765XXXXXX", "default":true}]}
{"enableManualInput": true, "hints": [{"msisdn":"+41765XXXXXX", "sn":"+574XXXXXX"}]}
{"enableManualInput": true, "hints": [{"msisdn":"+41765YYYYYY"},{"msisdn":"+41765XXXXXX", "default":true}]}
```
If an LDAP has been configured for your OIDC client, you can use the following login hints:
```json
{"useLDAP": true, "hints": [{"userName":"johndoe"}]}
{"useLDAP": true, "hints": [{"userName":"john.doe@acme.com", "userPassword":"plain-secret", "isHashed": false}]}
{"useLDAP": true, "hints": [{"userName":"john.doe@acme.com", "userPassword":"hashed-secret", "isHashed": true}]}
```
You can use the following login hint in combination with the `prompt=login` parameter:
```json
{"useLDAP": true}
```
If passkeys are enabled for your account, you can include the `keyringId` field in the login hint:
```json
{"hints": [{"msisdn":"+41765XXXXXX", "keyringId":"MIDPKXXXXXXXXXX"}]}
```
::: info
The `sn` parameter is optional and only required for ACR `mid_al4`. The `keyringId` is required for `mid_al4_passkey` and `mid_al4_any` (when passkeys are enabled). See [Passkey Authentication](/oidc-integration-guide/passkey-authentication) for details.
:::
#### DTBD Parameter
The `dtbd` message should include these keywords:
- `#SESSION#` — A unique transaction number. In case MFA Number Matching is enabled, this keyword will be replaced with the matching number.
- `#CLIENT#` — Relying Party Display Name.
The default authentication message is:
| Language | Message |
|----------|---------|
| English | Do you want to login to #CLIENT#? Transaction number #SESSION# |
| German | Möchten Sie sich bei #CLIENT# anmelden? Transaktion Nummer #SESSION# |
| French | Voulez-vous vous connecter à #CLIENT# ? Transaction numéro #SESSION# |
| Italian | Vuoi accedere a #CLIENT#? Transazione numero #SESSION# |
### Scopes and Claims
Given below is the list of supported scopes that can be requested during the authorization code request.
| Scope | Claim | Type | Example Value | Description |
|-------|-------|------|---------------|-------------|
| `openid` | `sub` | string | `3246d772d2edb208...` | Subject identifier (unique, pairwise per client) |
| `offline_access` | — | — | — | Requests a refresh token |
| `profile` | `name` | string | `+41791234567` | User's display name |
| `phone` | `phone_number` | string | `+41791234567` | Phone number in E.164 format |
| | `phone_number_verified` | boolean | `true` | Whether the phone number has been verified |
| `mid_location` | `mid_geo_accuracy` | number | `0` | GPS accuracy in meters |
| | `mid_geo_country` | string | `CH` | ISO country code of the device |
| | `mid_geo_device_confidence` | number | `1.0` | Device confidence score |
| | `mid_geo_location_confidence` | number | `1.0` | Location confidence score |
| | `mid_geo_timestamp` | string | `2022-03-17T05:49:03+01:00` | Timestamp of the geolocation measurement |
| `mid_profile` | `mid_profile_recovery_code_status` | boolean | `true` | Whether a recovery code has been set |
| | `mid_profile_serial` | string | `MIDCHEYUD1YE4QB1` | Mobile ID serial number |
| | `mid_pk_keyringid` | string | `MIDPK123A567B90` | Passkey keyring identifier |
| | `mid_profile_sim_status` | string | `active` | SIM card activation status |
| | `mid_profile_sim_pin_status` | string | `active` | SIM PIN status |
| | `mid_profile_sim_mcc` | string | `228` | Mobile Country Code |
| | `mid_profile_sim_mnc` | string | `01` | Mobile Network Code |
| | `mid_profile_sim_network` | string | `Swisscom` | Mobile network operator name |
| | `mid_profile_app_status` | string | `active` | Mobile ID App activation status |
| | `mid_profile_sscds` | string | — | Secure signature creation device descriptor |
| | `mid_profile_alias` | string | `John` | User-defined alias |
| `mid_cms` | `mid_cms_content` | string | — | CMS signed data (Base64-encoded) |
| `mid_esign_basic` | `mid_esign_basic_assurance_level` | string | `basic` | E-signature assurance level |
| | `mid_esign_basic_jurisdictions` | string | `CH` | Applicable jurisdictions |
| | `mid_esign_basic_has_valid_evidence` | boolean | `true` | Whether valid identity evidence exists |
| `mid_passkey` | `mid_pk_keyringid` | string | `MIDPK123A567B90` | Passkey keyring identifier |
| | `mid_pk_binding` | string | `device-bound` \| `syncable` | Whether the passkey is device-bound or synced |
| | `mid_pk_cert_level` | string | `FIPS140-2` \| `CommonCriteria` | Certification level of the authenticator |
| | `mid_pk_created_ts` | number | `1717584000` | Credential creation timestamp (Unix epoch) |
| | `mid_pk_last_used_ts` | number | `1717591234` | Last usage timestamp (Unix epoch) |
| | `mid_pk_aaguid` | string | `2fc0579f-8113-...` | [FIDO MDS](https://fidoalliance.org/metadata/) authenticator identifier |
| | `mid_pk_cred_fingerprint` | string | `pQECAyYgASFY...` | SHA-256 of the credential public key ([COSE](https://datatracker.ietf.org/doc/html/rfc9052)) |
| | `mid_pk_auth_attachment` | string | `platform` \| `cross-platform` | Authenticator attachment modality |
| | `mid_pk_os_family` | string | `iOS` \| `Android` \| `Windows` | OS family of the authenticator platform |
::: tip
A Relying Party should always respect the user's privacy and keep the requested claims down to the very essential. For example, using scope `openid` only, the user sign-in will be anonymous. Neither the phone number nor any other user information will be passed on to the Relying Party's application.
:::
Example claim values, retrieved from the UserInfo endpoint:
```json
{
"mid_geo_accuracy": 0,
"mid_geo_country": "CH",
"mid_geo_device_confidence": "1.0",
"mid_geo_location_confidence": "1.0",
"mid_geo_timestamp": "2022-03-17T05:49:03.597+01:00",
"mid_profile_recovery_code_status": true,
"mid_profile_serial": "MIDCHEYUD1YE4QB1",
"name": "+41791234567",
"phone_number": "+41791234567",
"phone_number_verified": true,
"sub": "3246d772d2edb20797fe9359cb3d07da6d01df7db2642e14554d241aef1d1d84"
}
```
### Authentication Context Class Reference (ACR)
Below is an overview of all authentication means offered and supported by Mobile ID OP. The ACR can be requested with an authorization request parameter — or, if the request does not contain such parameter, the client's default ACR is selected.
An ACR can include one or several different authentication methods. The Mobile ID OP will check the user's authentication possibilities and will select an authentication method that complies with the ACR.
Included
Excluded
Included, if 'Passkeys' feature is enabled for the client account
| acr_values | Authentication Method | Additional Checks | NIST-AAL3 | Remarks | ||||
|---|---|---|---|---|---|---|---|---|
 SIM |
 App |
 OTP |
 Passkey |
 CH |
 KeyRing |
|||
mid_al2_any |
|
|
|
|
|
|
|
Passkey-preferred, if passkeys_enabled:true for the client account.User can select a fallback method if Passkey Auth fails. Use this AL if UX is more important than security. Optional login_hint to provide MSISDN:{"enableManualInput": false, "hints": [{"msisdn":"+41765XXXXXX"}]} |
mid_al3_any |
|
|
|
|
|
|
|
See note [1] |
mid_al3_any_ch |
|
|
|
|
|
|
|
|
mid_al3_simcard |
|
|
|
|
|
|
|
|
mid_al3_mobileapp |
|
|
|
|
|
|
|
|
mid_al4_any |
|
|
|
|
|
|
|
Passkey-preferred, if passkeys_enabled:true for the client account.User can select a fallback method if Passkey Auth fails. Use this AL if security is important and phishing risk is acceptable. RP must provide SN and KeyRingId (if Passkey is enabled) in login_hint:{"enableManualInput": false, "hints": [{"msisdn":"+41765XXXXXX", "sn":"+574XXXXXX", "keyringId":"MIDPKXXXXXXXXXX"}]} |
mid_al4_any_ch |
|
|
|
|
|
|
|
|
mid_al4_simcard |
|
|
|
|
|
|
|
|
mid_al4_mobileapp |
|
|
|
|
|
|
|
|
mid_al4_passkey |
|
|
|
|
|
|
|
Passkey-only & phishing-resistant. Use this AL if security and phishing-resistance is important, with a trade-off that only Passkeys can be used. Optionally, this scenario may be used to comply with NIST AAL3, which requires the user to have a FIPS 140-2 certified authenticator (passkey) registered. RP must provide KeyRingId in login_hint:{"hints": [{"msisdn":"+41765XXXXXX", "keyringId":"MIDPKXXXXXXXXXX"}]} |
AL3: Mobile ID App (Account Recovery)
AL4: Mobile ID App (Account Recovery) | ::: warning If your client attempts to request an ACR that is not available with your current Mobile ID contract, an OIDC error `mid_sec_2020` ("unauthorized acr_values used in request", see [Error Scheme](/oidc-integration-guide/getting-started#error-scheme)) is returned. Please check with your commercial contact or via **Backoffice.Security@swisscom.com** if you are interested in ACR values that are listed in the table above but currently not configured for your Mobile ID OIDC account. ::: #### MID SN Check – AL4 Guide Using an ACR value of **Authentication Level 4** will provide the highest and most secure authentication level. The use of such ACR will require the Relying Party to always provide the Mobile ID's serial number via the `login_hint` authorization request parameter, if there is no LDAP configured. If an LDAP is configured, the Mobile ID server will lookup the user's serial number on the LDAP. The Mobile ID authorization server will compare the serial number with the serial number of the authentication response. The authentication will be successful if the serial numbers match. A serial number mismatch will result in an authentication failure. An account recovery (e.g., activate Mobile ID App) is supported and will result in a successful authentication if a valid user restore option was available and used during the recovery process. ::: info The Relying Party must implement its own Mobile ID user registration process to fetch and store the user's current Mobile ID serial number value. Technically, the best way to retrieve the user's current Mobile ID serial number is by starting an authorization request using authentication level 3 (for example `mid_al3_any`) and scope `mid_profile`, so that the Relying Party will retrieve the claim `mid_profile_serial`. ::: ### Example Authorization Code Request ```http HTTP/1.1 302 Found Location: https://m.mobileid.ch/oidc/authorize? response_type=code &scope=openid%20auth_basic &client_id=s6BhdRkqt3 &state=af0ifjsldkj &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb ``` ## Authorization Code Response The response to the authorize request will be an HTTP redirect that results in an HTTP GET request to the `redirect_uri` that was provided for the authorization code request with the following parameters: | Parameter | Value | |-----------|-------| | `code` | WILL contain the authorization code | | `state` | WILL contain the state | | `iss` | WILL contain the issuer of the authorization code: `https://openid.mobileid.ch` | ::: warning The authorization code is by default only valid for **10 seconds** after it has been issued. ::: ### Example Authorization Code Response ```http HTTP/1.1 302 Found Location: https://client.example.org/cb? code=SplxlOBeZQQYbYS6WxSbIA &iss=https%3A%2F%2Fopenid.mobileid.ch &state=af0ifjsldkj ``` ## Access Token Request The obtained authorization code ([see here](/oidc-integration-guide/getting-started#authorization-code-response)) can be used to receive an access token. This chapter describes how to format the access token request and which data is returned from the access token endpoint. The OpenID Connect RFC states that there are 4 possible client authentication methods (used by clients to authenticate to the Authorization Server when using the Token Endpoint). Mobile ID OP supports `client_secret_basic` or `client_secret_post` as client authentication method. The access token can be obtained by performing an HTTP POST request towards the Token endpoint of the Mobile ID OP. | Endpoint | URL | |----------|-----| | Token | https://openid.mobileid.ch/token | The following query string parameters need to be embedded in the request: | Parameter | Value | |-----------|-------| | `grant_type` | MUST be the value `authorization_code` | | `code` | MUST be the authorization code you received from Mobile ID (see [Authorization Code Response](/oidc-integration-guide/getting-started#authorization-code-response)) | | `redirect_uri` | MUST be the same redirect URI used in the authorization code request | | Headers | Value | |---------|-------| | `Authorization` | Client ID and client secret encoded according to the HTTP Basic authentication scheme | | `Content-Type` | MUST be the value `application/x-www-form-urlencoded` | ### Example Access Token Request In this example, basic authentication is used to authenticate the client to the Mobile ID server. ```http POST /token HTTP/1.1 Host: openid.mobileid.ch Content-Type: application/x-www-form-urlencoded Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW grant_type=authorization_code &code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb ``` ## Access Token Response After receiving and validating a valid and authorized token request from the client, the Authorization Server returns a successful response that includes: - **Access Token** - **ID Token** The response is returned in the `application/json` media type. The ID token is a JWT and is created (and thus signed, RS256 by default) by the Authorization Server itself. ### Authentication Method Reference (AMR) Authentication Method Reference (AMR) is an attribute within the OpenID Connect Identity Token. The AMR claim makes statements about the authentication method that was used (including additional factors such as geolocation).
Included
Excluded
| amr_values | Authentication Method | Remarks | |||
|---|---|---|---|---|---|
SIM |
App |
OTP |
Passkey |
||
mid_app |
|
|
|
|
|
mid_geo |
|
|
|
|
Only returned when an ACR with the _ch suffix was used (mid_al3_any_ch, mid_al4_any_ch), indicating that geolocation was verified to be in Switzerland (CH). |
mid_otp |
|
|
|
|
|
mid_sim |
|
|
|
|
|
mid_sms |
|
|
|
|
|
phr |
|
|
|
|
Standard AMR "Phishing-Resistant". Only for ACR mid_al4_passkey. |
hwk |
|
|
|
|
Standard AMR RFC 8176 "Hardware Key" |
Included
Excluded
Included, if 'Passkeys' feature is enabled for the client account
| acr_values | Authentication Method | Additional Checks | NIST-AAL3 | Remarks | ||||
|---|---|---|---|---|---|---|---|---|
SIM |
App |
OTP |
Passkey |
CH |
KeyRing |
|||
mid_al2_any |
|
|
|
|
|
|
|
Passkey-preferred, if passkeys_enabled:true for the client account.User can select a fallback method if Passkey Auth fails. Use this AL if UX is more important than security. Optional login_hint to provide MSISDN:{"enableManualInput": false, "hints": [{"msisdn":"+41765XXXXXX"}]} |
mid_al3_any |
|
|
|
|
|
|
|
See note [1] |
mid_al3_any_ch |
|
|
|
|
|
|
|
|
mid_al3_simcard |
|
|
|
|
|
|
|
|
mid_al3_mobileapp |
|
|
|
|
|
|
|
|
mid_al4_any |
|
|
|
|
|
|
|
Passkey-preferred, if passkeys_enabled:true for the client account.User can select a fallback method if Passkey Auth fails. Use this AL if security is important and phishing risk is acceptable. RP must provide SN and KeyRingId (if Passkey is enabled) in login_hint:{"enableManualInput": false, "hints": [{"msisdn":"+41765XXXXXX", "sn":"+574XXXXXX", "keyringId":"MIDPKXXXXXXXXXX"}]} |
mid_al4_any_ch |
|
|
|
|
|
|
|
|
mid_al4_simcard |
|
|
|
|
|
|
|
|
mid_al4_mobileapp |
|
|
|
|
|
|
|
|
mid_al4_passkey |
|
|
|
|
|
|
|
Passkey-only & phishing-resistant. Use this AL if security and phishing-resistance is important, with a trade-off that only Passkeys can be used. Optionally, this scenario may be used to comply with NIST AAL3, which requires the user to have a FIPS 140-2 certified authenticator (passkey) registered. RP must provide KeyRingId in login_hint:{"hints": [{"msisdn":"+41765XXXXXX", "keyringId":"MIDPKXXXXXXXXXX"}]} |
Included
Excluded
| amr_values | Authentication Method | Remarks | |||
|---|---|---|---|---|---|
SIM |
App |
OTP |
Passkey |
||
mid_app |
|
|
|
|
|
mid_geo |
|
|
|
|
|
mid_otp |
|
|
|
|
|
mid_sim |
|
|
|
|
|
mid_sms |
|
|
|
|
|
phr |
|
|
|
|
Standard AMR "Phishing-Resistant". Only for ACR mid_al4_passkey. |
hwk |
|
|
|
|
Standard AMR RFC 8176 "Hardware Key" |
Go to the [Microsoft Entra admin center](https://entra.microsoft.com) and log in to your Entra ID tenant as at least an Authentication Policy Administrator. For Step 8 (admin consent), you will need at least the Privileged Role Administrator role.
If you're using the [Azure portal](https://portal.azure.com), the navigation will differ slightly. | | 2 | **Navigate to Authentication Methods**
In the Entra Admin Center, go to **Entra ID → Authentication methods → Add external MFA**.
If you're logged into the Azure portal instead, first select Microsoft Entra ID, then go to **Security → Authentication Methods**. | | 3 | **Add External MFA**
Click **+ Add External MFA**.
 | | 4 | **Configure the External MFA Method**
On the "Add external MFA" page, enter a descriptive name for the MobileID method. The default name might be "Mobile ID" but you can choose a name that will make sense to your users since they'll see this during authentication.
**Note:** You cannot change the name after creation.
Enter the information you have received from Swisscom in the corresponding field: **Client ID**, **Discovery Endpoint**, **App ID**.
 | | 5 | **Enable the Method**
If you want to enable MobileID MFA right away, toggle Enable from "Off" to "On". | | 6 | **Specify Users**
Before saving the new MobileID external method, decide which users should have access to it.
By default, it will apply to all users, meaning any Entra ID user with a Conditional Access Policy requiring multifactor authentication (MFA) will see MobileID as an option.
To apply it to specific users, click **+ Add Target** under the "Include" tab and choose **Select Targets**. On the "Add directory members" page, select one or more Entra ID directory groups that contain the users you want to target for MobileID authentication, then click **Select**. | | 7 | **Save the Configuration**
After entering all the required details, click **Save** to create the new MobileID external method. | | 8 | **Grant Admin Consent**
If the "Request admin consent" information shows a **Request permission** button instead of saying "Admin consent granted", click the Request permission button to authorize the MobileID Authentication Method application, making sure to check the box next to **Consent on behalf of your organization** before clicking **Accept**.
You can verify the permissions if you go to **Identity → Applications → Enterprise applications** and select the MobileID Application, then select **Permissions**. The list of permissions that have been granted for your organization should be shown and it should look similar to this example below:
 | ### Create and Apply a Conditional Access Policy | Step | Description | |------|-------------| | 1 | **Log in to Entra ID**
Go to the [Microsoft Entra admin center](https://entra.microsoft.com) and log in to your Entra ID tenant as at least an Authentication Policy Administrator.
If you're using the [Azure portal](https://portal.azure.com), the navigation will differ slightly. | | 2 | **Navigate to Conditional Access**
Click on **Conditional Access** in the left-hand menu, then click **+ Create New Policy**.
If you are in the Azure portal, navigate to **Security → Conditional Access → Policies**.
 | | 3 | **Name the Policy**
Enter a descriptive name for the new policy, such as "MobileID MFA for Acme Users". | | 4 | **Assign the Policy**
You can assign this policy to specific users or groups, Entra ID cloud apps, or other conditions like client platforms or networks.
*Example for assigning to users:* Click **Users** under "Assignments", then select **Users and groups** on the "Include" tab. Choose **Users and groups** and click **0 users and groups selected** to locate the users or Entra ID security groups for whom you want to enforce MobileID MFA. Select the users or groups, then click **Select** to apply your choices.
If you targeted specific groups when creating the MobileID external method, ensure that you apply this new policy to the same groups.
*Example for assigning to resources:* Click **Target resources**. On the "Include" tab, select **Apps**, and choose the Entra ID applications where you want MobileID MFA to be applied. | | 5 | **Configure Access Controls**
Click **Grant** under "Access controls", select **Grant access**, and check the box for **Require multifactor authentication**. Click **Select** when done.
 | | 6 | **Enable the Policy**
The final step is to enable the new MobileID conditional access policy. Click the "On" toggle switch under "Enable policy", then click **Create**. The policy will be created and applied to your selected groups or users, enforcing MFA via MobileID. | ::: warning Avoid assigning the MobileID policy to all users or all cloud apps at the start, especially for tenant administrators, to prevent potential admin lockouts. Always test the policy with selected users first. Additionally, ensure you create a fail-safe Entra ID administrator account that is excluded from MobileID MFA policies to maintain uninterrupted access. Secure this account with a strong password and a different access condition, such as one based on a trusted network. ::: ### Additional Configuration to Prioritize MobileID MFA If you want users to exclusively use MobileID instead of the Microsoft Authenticator app, follow these steps: | Step | Description | |------|-------------| | 1 | **Disable the Microsoft Authenticator Registration Campaign**
In the Entra ID admin center, go to **Protection → Authentication Methods → Registration Campaign**.
Click **Edit**, change the State to **Disabled**, and click **Save**.
Alternatively, you can leave the registration campaign enabled and exclude the groups of users who are covered by the MobileID conditional access policy. | | 2 | **Disable System Preferred MFA for Microsoft Authenticator**
Go to **Protection → Authentication Methods → Settings → System Preferred Multifactor Authentication**.
Click **Edit**, change the State to **Disabled**, and click **Save**. | | 3 | **Turn Off Microsoft Authenticator**
Navigate to **Protection → Policies**, click **Microsoft Authenticator**.
On the "Enable and Target" tab, toggle the Enable switch to **Off** and click **Save**. | ### Test Your Setup Log in to Entra ID using a user account that has been assigned the Conditional Access policy requiring MFA and is a target for the newly created MobileID external method. If you applied the MobileID Conditional Access policy to "All cloud apps", when you log into the Office portal (e.g., [https://office.com](https://office.com)) and submit your primary Entra ID credentials, you'll see your MobileID External MFA method as an option for identity verification. The name displayed will be the one you entered when setting up the MobileID External MFA method in Entra ID.
Choose the "Mobile ID" method to begin MobileID MFA authentication.
If you have multiple Entra ID authentication methods enabled, you may need to click "Other options" to view and select the MobileID method.
You will be redirected to the MobileID prompt or user enrolment, depending on your configuration.
Once you complete the MobileID authentication, you'll return to Entra ID to finish logging in to the application.
If your Conditional Access policy requiring MFA is only applied to specific applications, the initial login to the Office portal will not prompt for MobileID MFA. However, accessing the protected application within the Office portal or directly will trigger the MobileID MFA prompt.
::: warning
If you encounter the "Looks like something went wrong" error from Microsoft, the new External MFA settings might need additional time to propagate. If the error persists, you may request support from Swisscom.
:::
### Troubleshooting
Need some help? Please ask your commercial contact or get in touch with **Backoffice.Security@swisscom.com** to ask for support.
## 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.
::: 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.
::: 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.
:::
---
## OIDC Use Cases
Source: https://docs.mobileid.ch/oidc-integration-guide/oidc-use-cases.html
# 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.
::: info
The Relying Party won't know the user's MSISDN unless the user gives their consent.
:::
## RP knows the MSISDN
If the request contains a `login_hint` parameter with the user's phone number, the MobileID authentication can start immediately.
## Prompt 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.
::: tip
Instead of the MobileID domain (`m.mobileid.ch`), we can configure your custom domain instead.
:::
## 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.
---
## OIDC Message Formats
Source: https://docs.mobileid.ch/oidc-integration-guide/message-formats.html
# Message Formats on the Mobile ID App
Mobile ID App screens can present the Data-To-Be-Displayed (DTBD) in two formats.
::: tip
Use **Classic DTBD** for short confirmations and when you must support SIM users. Keep messages concise and always include the "DTBD Prefix".
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.
:::
1. **Classic DTBD** (single text line) uses a plain UTF-8 string that is also signed (DTBS).
Supported by SIM and App methods.
Length limited and no formatting options.
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.
## 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.
::: warning
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**.
:::
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.
::: warning
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": "
Since nodes need a way of communicating between them and considering the specific target runtime environment, a good approach for this inter-node synchronization is via a common **Redis database cluster**. Each node connects to this database and is able to save and read data from all the other nodes in a RIG cluster. An ongoing authentication session, for example, will have its data stored by node A in the Redis database, with node B later reading the data for that session and carrying it on.
Requests coming from outside of the RIG cluster reach a proxy service and are then dispatched to one appropriate RIG node. It is up to the proxy to select the right node, but any policy will work fine, as all RIG nodes have the same quality and level of data access, so any one of them could handle a request at any time. Of course, the proxy is responsible for carefully distributing the load on available nodes, but from the point of view of the RIG nodes, the functionality is the same, regardless of the chosen node.
### Single-Node Deployment (without Redis)
For smaller deployments or proof-of-concept setups, RIG can be deployed as a single container instance without a Redis database. In this mode, session state is stored in-memory. This is suitable when:
- Only **SIM** and/or **APP** authentication methods are used (no OTP)
- High availability and horizontal scaling are not required
This deployment mode significantly reduces infrastructure requirements — only a single RIG container is needed. See the [Deployment](/radius-interface-gateway-guide/deployment) page for configuration details.
Moving one level down in the architectural view, the following diagram shows the main logical parts of the RIG service:
## Authentication Methods
One of the main components of the RIG service is responsible for managing the authentication methods that are available for a client and selecting the right method on a per-user basis.
The following authentication methods are currently supported:
- **SIM Digital Signature** — The user is prompted to confirm a transaction (RADIUS authentication session) and create a digital signature using his/her Mobile ID-enabled SIM chip.
- **App Digital Signature** — Like the SIM method above, but the signing "device" is a mobile application with its keys protected by the phone's system protection.
- **OTP over Text SMS** — An OTP code is generated for each authentication session and sent to the user via an SMS message. A RADIUS Access-Challenge + Access-Request round trip is used to challenge the user to enter the OTP received via SMS.
For each RADIUS client configured for the RIG service, the following parameters need to be specified:
- The **available authentication methods**
- The **default method**, in case all other methods are unavailable
During an authentication session, the RIG service loads this configuration and tries to match it to the current state of the user's Mobile ID account.
Each customer account can have its custom list of allowed MFA methods with its own order of priority. An LDAP user attribute may be used to set a preferred MFA option per user (if the configuration parameter `UseUserMfaMethod` is set to `true`). This will always override any other configured order of priority.
If a preferred MFA option (from an LDAP user attribute) is not active or not allowed by the customer configuration, the system falls back to the next MFA option according to the configured order of priority.
---
## RADIUS RIG Deployment
Source: https://docs.mobileid.ch/radius-interface-gateway-guide/deployment.html
# RIG Deployment
There are different types of container services you may use to deploy and run microservices like the RIG application in a high-availability setup.
We generally recommend using **Kubernetes** or similar container orchestration options to have a platform that automates the tasks related to the management, deployment, and scaling of container clusters.
Docker images and Helm charts may be used. The latter one facilitates the packaging and deployment of more complex setups in target Kubernetes environments. This works if the customer is already operating a Docker/Swarm environment or a Kubernetes one.
If simpler setups are needed, the RIG service and dependent components can be delivered and installed as standard software applications.
## Preconditions
The following points must be considered before you proceed with the deployment.
### General Requirements
- A Mobile ID contract exists. You know your `AP_ID` and your API key (PFX/PKCS#12 format).
- A Directory Service (LDAP) exists, which contains user attributes such as name and phone number.
- An appropriate security concept exists (e.g. secured network communication, hardening, etc.).
### NAS Requirements
- The NAS RADIUS Access-Request packet contains either a **unique NAS-Identifier attribute** or it has a **unique and static source IP address/range**. RIG will pick the configuration based on this info.
- The RADIUS client timeout shall be set to **60 seconds**. This ensures enough time for the user to respond to the Mobile ID authentication request.
- The RADIUS client retry shall be set to no more than **1**. The client should not retry because there might still be a Mobile ID authentication session ongoing.
### Connectivity Requirements
Connectivity must be allowed as follows:
- **RADIUS** (UDP/1812) — Requests from your NAS (e.g. VPN server) to the RIG application (or the UDP network load balancer that forwards the requests to the RIG application nodes).
- **LDAPS** (TCP/636) — From the RIG application to your LDAP server.
- **HTTPS** (TCP/443) — From the RIG application to the Mobile ID API endpoint at `mobileid.swisscom.com` (Internet) or `195.65.233.218` ([EC](https://www.swisscom.ch/en/business/enterprise/offer/wireline/enterprise-connect.html)).
- **REDIS** (TCP/6379) — Between the RIG application nodes and the Redis database cluster.
- **HTTP** (TCP/80) — Local connectivity for the Docker health check (optional).
You can verify the LDAP connectivity using the following command on the node where the RIG container application is running. You may also use `ldaps` (port 636) instead of `ldap` (port 389):
```bash
ldapwhoami -x -w 
**Step 1** — The user opens the VPN client (the Supplicant) on his/her laptop and clicks on the desired VPN connection. Since the user does not want to store credentials locally, the VPN client asks for the username and password. The user enters the requested credentials.
**Step 2** — The VPN client initiates a specific protocol connection (e.g. PPTP, L2TP/IPSec, etc.) to the VPN server, transmitting the username and password. The VPN server is configured to use RADIUS as the authentication protocol.
**Step 3** — The VPN server creates a RADIUS Access-Request packet using its RADIUS shared secret, the username and password received from the VPN client, and the type of service the user requested: VPN. The RADIUS packet is sent to the client's backend RADIUS server.
```
Code: Access-Request
Identifier: 15
Authenticator: D23B55123DB54103
Attributes:
- NAS-Identifier: digitec-vpn-iop
- User-Name: john
- User-Password: md5("secret"+Authenticator)
```
**Step 4** — The RADIUS server validates all aspects of the received request: the shared secret, the user password, and permissions. It also checks if there are other extra authentication steps required for this user. It finds that this user has multi-factor authentication (MFA) enabled via Mobile ID.
**Step 5** — To use Mobile ID as MFA, the flow needs to go through the RIG service. For this to happen, the RADIUS server needs the MSISDN of the currently authenticating user. It makes a local query to its data store and finds the MSISDN of the user based on the given username.
An alternative at this step is for mobile users to directly enter the username as a construct of `
**Step 1** — The user opens the VPN client (the Supplicant) on his/her laptop and clicks on the desired VPN connection. Since the user does not want to store credentials locally, the VPN client asks for the username and password. The user enters the requested credentials.
**Step 2** — The VPN client initiates a specific protocol connection (e.g. PPTP, L2TP/IPSec, etc.) to the VPN server, transmitting the username and password. The VPN server is configured to use RADIUS as the authentication protocol.
**Step 3** — The VPN server creates a RADIUS Access-Request packet using its RADIUS shared secret, the username and password received from the VPN client, and the type of service the user requested: VPN. The RADIUS packet is sent to the client's backend RADIUS server.
```
Code: Access-Request
Authenticator: a23b55123d...
Attributes:
- NAS-Identifier: digitec-vpn-iop
- User-Name: john
- User-Password: pass4john
```
**Step 4** — The RADIUS server validates all aspects of the received request: the shared secret, the user password, and permissions. It also checks if there are other extra authentication steps required for this user. It finds that this user has multi-factor authentication (MFA) enabled via Mobile ID.
**Step 5** — To use Mobile ID as MFA, the flow needs to go through the RIG service. For this to happen, the RADIUS server needs the MSISDN of the currently authenticating user. It makes a local query to its data store and finds the MSISDN of the user based on the given username.
An alternative at this step is for mobile users to directly enter the username as a construct of `
**Step 2** — The VPN client initiates a specific protocol connection (e.g. PPTP, L2TP/IPSec, etc.) to the VPN server, transmitting the username and password. The VPN server is configured to use RADIUS as the authentication protocol.
**Step 3** — The VPN server creates a RADIUS Access-Request packet using its RADIUS shared secret, the username and password received from the VPN client, and the type of service the user requested: VPN. The RADIUS packet is sent to the RIG service for processing.
```
Code: Access-Request
Authenticator: A23B55123DB54103
Attributes:
- NAS-Identifier: mid-digitec-vpn
- User-Name: 40712345678@client.com
- User-Password: not-used
```
**Step 4** — The RIG service receives the request and proceeds to validate the NAS identifier and the shared secret of the client. Based on the client's configuration, the RIG service decides how to proceed and what parameters to use for the next step:
- Based on the authentication method algorithm configured for this client, an array of possible methods is selected. These can be any of SIM-based digital signature, app-based digital signature, OTP over SMS, or any other method that will be implemented in future versions.
- From the User-Name received from the RADIUS client, the user's MSISDN is extracted.
- Based on an MSS Profile Query for the user's MSISDN, the appropriate method of authentication is selected. If the user has an active Mobile ID account, the method could be SIM- or App-based digital signature. If the user has issues with the Mobile ID account or has no such account, the chosen method could be OTP over SMS. For the current use case, the user has an active Mobile ID account, so the flow continues with a SIM/App-based digital signature authentication (see [Authentication Methods](/radius-interface-gateway-guide/introduction#authentication-methods) for more information).
- The AP ID, AP password, signature profile, and the DTBS are extracted and prepared from the client's configuration.
**Step 5** — The RIG service connects to Mobile ID and sends the MSS Signature Request. The operation is asynchronous, so it receives an instant response along with an `AP_TransID` to use in subsequent polls. On its side, the Mobile ID service sends a signature request to the user's mobile device (via SIM or mobile app).
**Step 6** — The user confirms the transaction and authenticates via PIN or fingerprint. A digital signature is created on the mobile device and returned to Mobile ID.
**Step 7** — In one of its MSS Status Query polls, the RIG service receives the response with a finished signature status and the digital signature content.
**Step 8** — After validating the signature, the RIG service decides to accept the user's authentication request. At this point, there are no further checks performed (e.g. proper user authorization) as the RIG service is not in the position of authorizing the user. Therefore, it creates a RADIUS Access-Accept packet with an access reply message (created from the client's configuration) and sends the packet back to the RADIUS client (i.e. VPN server) that called it.
```
Code: Access-Accept
Identifier: 15
Authenticator: ec89a776d8cdea8675ac7
Attributes:
- Login-Service: VPN
- Reply-Message: Authentication successful!
```
**Step 9** — The VPN server receives the Access-Accept packet and proceeds to provide the user with the requested service (i.e. establishes the VPN connection).
### MFA with LDAP
This scenario presents a setup where the RIG service is configured as the only RADIUS server in a client's network. It uses a local LDAP directory instance for validating the user's credentials and the Mobile ID service for second-factor authentication via a mobile signature. In this scenario, the MSISDN is not sent as part of the RADIUS User-Name attribute but is resolved by the RIG service via the LDAP directory.
**Step 1** — The user opens the VPN client (the Supplicant) on his/her laptop and clicks on the desired VPN connection. Since the user does not want to store credentials locally, the VPN client asks for the username and password. The user enters the username (e.g. `jack@client.com`) and the password.
**Step 2** — The VPN client initiates a specific protocol connection (e.g. PPTP, L2TP/IPSec, etc.) to the VPN server, transmitting the username and password. The VPN server is configured to use RADIUS as the authentication protocol.
**Step 3** — The VPN server creates a RADIUS Access-Request packet using its RADIUS shared secret, the username and password received from the VPN client, and the type of service the user requested: VPN. The RADIUS packet is sent to the RIG service for processing.
```
Code: Access-Request
Authenticator: A23B55123DB54103
Attributes:
- NAS-Identifier: mid-digitec-vpn
- User-Name: jack@client.com
- User-Password: s3cr3t
```
**Step 4** — The RIG service receives the request and proceeds to validate the NAS identifier and the shared secret of the client.
**Step 5** — Based on the client's configuration, the RIG service performs a query on the configured LDAP directory, retrieving the user password and MSISDN based on the received username.
**Step 6** — The retrieved LDAP data is used in this step to perform the first-factor authentication: validate the user-supplied password.
**Step 7** — Based on an MSS Profile Query for the user's MSISDN, the appropriate method of authentication is selected. If the user has an active Mobile ID account, the method could be SIM- or App-based digital signature. If the user has issues with the Mobile ID account or has no such account, the chosen method could be OTP over SMS. For the current use case, the user has an active Mobile ID account, so the flow continues with a SIM/App-based digital signature authentication (see [Authentication Methods](/radius-interface-gateway-guide/introduction#authentication-methods) for more information). The AP ID, AP password, signature profile, and the DTBS are extracted and prepared from the client's configuration.
**Step 8** — The RIG service connects to Mobile ID and sends the MSS Signature Request. The operation is asynchronous, so it receives an instant response along with an `AP_TransID` to use in subsequent polls. On its side, the Mobile ID service sends a signature request to the user's mobile device (via SIM or mobile app).
**Step 9** — The user confirms the transaction and authenticates via PIN or fingerprint. A digital signature is created on the mobile device and returned to Mobile ID.
**Step 10** — In one of its MSS Status Query polls, the RIG service receives the response with a finished signature status and the digital signature content.
**Step 11** — After validating the signature, the RIG service decides to accept the user's authentication request. At this point, there are no further checks performed (e.g. proper user authorization) as the RIG service is not in the position of authorizing the user. Therefore, it creates a RADIUS Access-Accept packet with an access reply message (created from the client's configuration) and sends the packet back to the RADIUS client (i.e. VPN server) that called it.
```
Code: Access-Accept
Identifier: 15
Authenticator: ec89a776d8cdea8675ac7
Attributes:
- Login-Service: VPN
- Reply-Message: Authentication successful!
```
**Step 12** — The VPN server receives the Access-Accept packet and proceeds to provide the user with the requested service (i.e. establishes the VPN connection).
## SMS Notifications
The most secure authentication method for users is to use Mobile ID with SIM- or app-based digital signatures. This, however, requires an active Mobile ID account, which is something that users might not have immediately available during a RADIUS authentication session. For this reason, after an authentication session is finished successfully (say, with a fallback to OTP over SMS, where the OTP is correctly provided by the user), the RIG service will follow up with the respective user with an SMS notification to help the user kick-start the process of fixing the issue with the Mobile ID account (or create an account altogether).
The RIG service cannot provide the UI required for fixing any account issues or guide the user into creating a new Mobile ID account. For these reasons, the SMS text sent as a delayed notification will contain a friendly message adapted to the respective account situation and a link to the Mobile ID user portal where the user can create a new account or fix any existing issues.
For each RADIUS client configured for the RIG service, the following delayed notifications are available:
| Account Situation | Notification Message |
|---|---|
| No Mobile ID account | "Create a new Mobile ID account by visiting the Mobile ID portal. `https://link`" |
| Account present, not active | "You can activate your Mobile ID account by visiting the Mobile ID portal. `https://link`" |
| Account present, PIN blocked | "We noticed your Mobile ID account has its PIN blocked. Visit the Mobile ID portal to unblock it. `https://link`" |
These messages are configurable on a per-client basis, including the template for each of the four supported Mobile ID languages, the time between notifications, and the total number of SMS messages to send per user (to prevent user spamming).
## LDAP Authentication
In the previous chapters, we discussed various service setups, one of which could have the RIG service installed on the client's premises (either physical premises or client-managed cloud environment). For this setup, if the RIG service needs to act as the main (or only) RADIUS server, it needs to perform both username + password authentication and the second-factor authentication via Mobile ID. To accomplish this, one option is to enable the RIG service to validate user's credentials against an LDAP server.
The following diagram presents this setup:
By configuration, the RIG service can connect to a local LDAP server and validate the received RADIUS User-Name and User-Password against a set of LDAP user attributes. Once this validation is successful, the service can move to the Mobile ID-based authentication part of the flow.
This feature allows the RIG service to be a quick drop-in replacement for the existing RADIUS server for clients that already have this combination (RADIUS + LDAP database).
---
## RADIUS Configuration
Source: https://docs.mobileid.ch/radius-interface-gateway-guide/configuration.html
# Configuration
This page describes how to configure the RIG application for your environment. RIG supports two configuration sources:
| Source | Storage | Best for |
|--------|---------|----------|
| **KeyValueStorage** (Redis) | Customer configs and I18N messages stored as JSON in Redis | Production / multi-node clusters |
| **AppSettings** (Environment Variables) | All configuration provided via environment variables | Single-node deployments without Redis |
The configuration source is controlled by these environment variables:
```bash
# Set to 'KeyValueStorage' (Redis) or 'AppSettings' (Environment Variables)
RadiusServer__CustomerConfigSource=KeyValueStorage
RadiusServer__I18nMessagesSource=KeyValueStorage
```
## Customer Configuration (Redis)
When using Redis, add the customer configuration as a JSON string to your Redis database:
- **Key:** `CUSTOMER_CONFIG_
The configured RADIUS server receives the packet and proceeds to check the validity of the data and authenticate the user. At this point, the behavior depends on the configuration of the RADIUS server and the process that is required for authenticating and authorizing the user. The RADIUS server might contact other servers to complete the authentication and authorization process and decide on a positive (accept) or negative (reject) response.
In the diagram above, the RADIUS server decided to inform the NAS client that the user's request is OK and that the requested service can be provided. For this, the RADIUS server sends back a RADIUS packet with code 2 (`Access-Accept`). Should it decide to reject the user's request, the RADIUS server would send back to the NAS client a packet with code 3 (`Access-Reject`).
As the final step in our flow, the NAS client receives the response packet from the RADIUS server and, if it has an `Access-Accept` code, it moves on to providing the requested service (e.g. establishing a VPN connection).
### Challenge and Response
Based on the configuration for a user and during an authentication session, the RADIUS server can decide to perform a challenge/response authentication. This flow introduces a few more steps in the standard RADIUS flow:
1. After the RADIUS server receives the first RADIUS Access-Request, it sends back to the RADIUS client an **Access-Challenge** response (instead of an Access-Accept or Access-Reject). The response packet contains a challenge code that the user is expected to enter in a security device (smart card or software application) and obtain a response.
2. The RADIUS client receives the Access-Challenge response and uses its custom protocol with the Supplicant application to transfer this challenge and present it to the user.
3. The Supplicant application (e.g. VPN client application) displays the challenge to the user and instructs him/her to enter the challenge code into the security device, calculate the response code, and enter that code back in the UI.
4. The user performs the computation and enters the code back.
5. The Supplicant application sends the response code back to the RADIUS client which, in turn, creates a new RADIUS Access-Request packet, this time with the User-Password field set to the challenge response.
6. The RADIUS server identifies the ongoing authentication session, checks the challenge response, and decides whether to accept the request or not. Depending on the decision, the RADIUS server sends back either an `Access-Accept` (request accepted), an `Access-Reject` (request rejected), or another `Access-Challenge` (more challenge round trips are required).
7. Finally, the Supplicant application and the RADIUS client act together based on the response from the RADIUS server: either give the user access to the service, reject the user, or challenge further.
The diagram below depicts the Challenge/Response flow:
The goal of the RADIUS Challenge/Response flow is to increase the strength of the authentication process by using a two-factor authentication: User-Name + User-Password (something the user knows) and the challenge code calculation (something the user has — the security device).
### RADIUS via Proxies
The RADIUS protocol allows network architectures where certain RADIUS server components act as proxies between a RADIUS client and a remote (final) RADIUS server. Whether this is for roaming/federation purposes or for enhancing an authentication session with input from more than one RADIUS server, using RADIUS proxies is an easy and transparent way of assembling a custom authentication flow:
1. The authentication session starts as usual, with the user requesting a particular service to a Supplicant application. The request is sent via a specific protocol to the backend service that acts as a RADIUS client in this case.
2. The RADIUS client assembles an Access-Request packet and sends it to the configured RADIUS server.
3. Based on the configuration for this RADIUS client or user, the RADIUS server decides to proxy the request, so it sends the Access-Request to the next RADIUS server. For the diagram below, this server is again a proxy, so this step is repeated once more.
4. The Access-Request packet finally lands on the remote RADIUS server. After the due security checks and authorizations, the remote RADIUS server can issue any of an Access-Accept, Access-Reject, or Access-Challenge.
5. The response travels back, from service to service, in reverse order, until it reaches the RADIUS client. At this point, the client acts based on the received response type (accepts or rejects the service or takes the user through a challenge).
The following diagram depicts this scenario:
The Proxy scenario is a good asset for assembling a RADIUS-based network. It allows administrators to change the topology of the network without affecting existing RADIUS clients (e.g. VPN server endpoints), existing applications installed on users' machines, or the users' current behavior.
---
## RADIUS Annexes
Source: https://docs.mobileid.ch/radius-interface-gateway-guide/annexes.html
# Annexes
## RADIUS-related RFCs
The following list contains a set of RFCs that cover the various aspects of the RADIUS protocol and that will come in handy for implementing the solution outlined in this document:
| RFC | Title |
|-----|-------|
| [RFC 2865](https://datatracker.ietf.org/doc/html/rfc2865) | Remote Authentication Dial-In User Service (RADIUS) |
| [RFC 2866](https://datatracker.ietf.org/doc/html/rfc2866) | RADIUS Accounting |
| [RFC 2867](https://datatracker.ietf.org/doc/html/rfc2867) | RADIUS Accounting Modifications for Tunnel Protocol Support |
| [RFC 2868](https://datatracker.ietf.org/doc/html/rfc2868) | RADIUS Attributes for Tunnel Protocol Support |
| [RFC 2869](https://datatracker.ietf.org/doc/html/rfc2869) | RADIUS Extensions |
| [RFC 3162](https://datatracker.ietf.org/doc/html/rfc3162) | RADIUS and IPv6 |
| [RFC 3575](https://datatracker.ietf.org/doc/html/rfc3575) | IANA Considerations for RADIUS |
| [RFC 3579](https://datatracker.ietf.org/doc/html/rfc3579) | RADIUS Support for Extensible Authentication Protocol |
| [RFC 3580](https://datatracker.ietf.org/doc/html/rfc3580) | IEEE 802.1X RADIUS Usage Guidelines |
| [RFC 5080](https://datatracker.ietf.org/doc/html/rfc5080) | Common RADIUS Implementation Issues and Suggested Fixes |
| [RFC 6158](https://datatracker.ietf.org/doc/html/rfc6158) | RADIUS Design Guidelines |
| [RFC 6572](https://datatracker.ietf.org/doc/html/rfc6572) | RADIUS Support for Proxy Mobile IPv6 |
| [RFC 6613](https://datatracker.ietf.org/doc/html/rfc6613) | RADIUS over TCP (updated by [RFC 7930](https://datatracker.ietf.org/doc/html/rfc7930)) |
| [RFC 6614](https://datatracker.ietf.org/doc/html/rfc6614) | Transport Layer Security (TLS) Encryption for RADIUS |
| [RFC 6929](https://datatracker.ietf.org/doc/html/rfc6929) | RADIUS Protocol Extensions |
| [RFC 7268](https://datatracker.ietf.org/doc/html/rfc7268) | RADIUS Attributes for IEEE 802 Networks |
| [RFC 7930](https://datatracker.ietf.org/doc/html/rfc7930) | Larger Packets for RADIUS over TCP |
| [RFC 8044](https://datatracker.ietf.org/doc/html/rfc8044) | Data Types in RADIUS |
| [RFC 2607](https://datatracker.ietf.org/doc/html/rfc2607) | Proxy Chaining and Policy Implementation in Roaming |
## RADIUS Testing Tools
For testing a running instance of the RIG service (or any other RADIUS server), the following tools can be used.
### Radclient
The Radclient is a small RADIUS client program that can be used from the command line to send RADIUS packets and print the received responses. Input data can be given via program arguments or with a local configuration file.
It can be used like this:
```bash
echo "User-Name = test" | /usr/local/bin/radclient localhost:1812 auth s3cr3t
```
```bash
echo "User-Name=test,User-Password=mypass,Framed-Protocol=PPP" | \
/usr/local/bin/radclient localhost:1812 auth s3cr3t
```
```bash
echo "Message-Authenticator = 0x00" | /usr/local/bin/radclient localhost:1812 auth s3cr3t
```
#### Testing a RIG Instance
The following examples show how to use `radclient` to test a running RIG instance specifically.
**Without LDAP** — the MSISDN is provided as part of the User-Name:
```bash
radclient -c 1 -r 1 -x -t 30 
### NTRadPing Test Utility
The NTRadPing application is a Windows desktop application that can be used for testing a RADIUS server. Since it runs from a local machine, it can easily test any internal/private RADIUS service.
Here is a screenshot from the application:
### Other Tools
There are other tools that could come in handy during the development and testing phases of the RIG service. For example, the **Simple Radius Test Tool** is an ad-supported Android application that functions as a RADIUS client, and **RadPerf** is a load testing tool for RADIUS servers.
---
## Release Notes Mobile ID Passkeys Launch (2026-03-30)
Source: https://docs.mobileid.ch/release-notes/posts/2026-03-30-mobile-id-passkeys.html
Microsoft blocks roughly 7,000 password attacks per second every day, and 47% of consumers abandon a purchase when they forget their password. In a world where phishing remains the most common attack vector, a fundamentally new answer is needed. Passkeys are that answer. Mobile ID now integrates them natively into its OIDC ecosystem and combines them with the proven strengths of SIM and App.
## NIST AAL: The Reference Framework for Security Levels
Before examining each method in detail, a shared understanding of security levels is essential. The NIST standard SP 800-63B defines three Authenticator Assurance Levels (AAL), which serve as the reference framework in regulated industries such as banking, healthcare and government.
**AAL1** requires only single-factor authentication. Passwords, SMS OTPs or simple tokens satisfy this level. The security level is low.
**AAL2** requires two different factors. In addition, a phishing-resistant option must be offered for online services. Cloud-synced Passkeys, TOTP generators, Mobile Push (such as Mobile ID SIM or App) and multi-factor OTP devices meet AAL2.
**AAL3** is the highest level. It requires public-key cryptography, a hardware module validated to FIPS 140 Level 2 or higher, phishing-resistant methods and a non-exportable private key. Re-authentication after 15 minutes of inactivity is also required. Only a few authenticators fully meet these requirements: FIPS-certified security keys (e.g. YubiKey 5 FIPS Series), certain smartcards and hardware security modules.
## What Are Passkeys?
Passkeys are a user-friendly implementation of the FIDO2 standard and the WebAuthn API. They replace passwords with cryptographic key pairs and enable login via biometrics in under 3 seconds. The core principle: the private key never leaves the user's device. Instead, the authenticator signs a challenge that the server verifies with the public key.
What makes Passkeys special is origin binding: the key is cryptographically bound to the domain of the service. Even if a user lands on a perfectly replicated phishing site, authentication fails because the browser detects the wrong domain and refuses to release the key.
## Passkey Types: Convenience vs. Maximum Security
Not all Passkeys are created equal. Different types are used depending on the level of protection required. The choice directly affects the achievable security level.
### Cloud-Synced Passkeys
Cloud-synced Passkeys are synchronized via the platform provider's cloud infrastructure: Apple iCloud Keychain, Google Password Manager or third-party managers such as 1Password. In mainstream consumer ecosystems, cloud synchronization has become the default user experience because it maximizes recovery and cross-device convenience.
The major advantage: Passkeys are available across all devices within the same ecosystem. If a device is lost, access is retained through other devices. Synchronization uses end-to-end encryption. Cloud-synced Passkeys can also be shared with family members or friends, which also means they can end up on untrusted devices.
Security level: **AAL2**. Since the keys are exportable and reside in cloud infrastructures (which are subject to the US CLOUD Act), they do not meet the requirements for AAL3.
### Device-Bound Passkeys
With device-bound Passkeys, the private key never leaves the security hardware. Typical examples are FIPS-certified security keys such as the YubiKey 5 FIPS Series (FIPS 140-2 Cert #3907, approx. CHF 100 at Digitec). These offer the highest security and are AAL3-compliant.
Important to know: standard YubiKeys (without FIPS certification) are not sufficient for AAL3. In September 2024, a severe vulnerability was also discovered in the YubiKey 5 Series that cannot be fixed via firmware update but requires a physical replacement of the token. This illustrates a fundamental problem with physical tokens: security flaws can be expensive and cumbersome to resolve.
Security level: **AAL3** (only with FIPS 140-2 certification and firmware 5.7 or newer).
### Platform Authenticators
Platform authenticators are security modules built directly into the device, such as Windows Hello (TPM), Apple Touch ID/Face ID (Secure Enclave) or the Titan M2 chip in Google Pixel devices. Depending on configuration, they can function as cloud-synced or device-bound.
AAL3 is only achievable if the key is not synchronized to the cloud and the hardware component is FIPS-validated. In practice, this requires a device-bound configuration or an external authenticator that keeps the private key outside a cloud-synced credential store.
### 3rd-Party Passkey Providers
Since iOS 17 and Android 14, third-party providers can register as Passkey providers. The Credential Manager API (Android) and AuthenticationServices (iOS) allow authentication apps to create and manage Passkeys without relying on the system's built-in Passkey store.
This is the technical foundation for the planned Mobile ID Passkey Vault: the Mobile ID App itself becomes a Passkey provider and can manage device-bound Passkeys at AAL3 level, without requiring physical hardware tokens.
## Passkey Integration: Simple for Users, Complex for Enterprises
Passkeys promise a simple user experience. The technical reality behind the scenes, however, is demanding. A complete Passkey infrastructure requires:
A **WebAuthn backend** with FIDO2 server library, attestation validation, credential management and secure key storage. A **credential lifecycle management** system for registration, deactivation, recovery and managing multiple Passkeys per user. **Fallback mechanisms** for users without a Passkey-capable device or when authentication fails. **Compliance checks** for regulated industries, including AAGUID validation against the FIDO Metadata Service (MDS) database and FIPS certification verification.
Mobile ID resolves this complexity: Relying Parties do not integrate the Passkey infrastructure themselves but rather the Mobile ID OIDC Service. Passkey registration and management takes place centrally on mobileid.ch. A Passkey is registered once and can then be used across all connected Relying Parties.
For enterprises, this means a standard OIDC integration with configurable ACR values, automatic fallback to SIM, App or SMS, and the assurance of a partner like Swisscom that uses these solutions itself to protect highly critical infrastructures.
## Security Profile by Usage Context
All Mobile ID methods provide strong authentication. The optimal choice depends on the use case scenario. The key distinction: is this an open browser scenario with a freely chosen URL, or a closed journey?
### Browser Journeys: Open URLs and Phishing Risk
In the browser, the user navigates freely. They can click links in emails, type URLs manually or reach pages via search engines. This is where phishing risk is greatest: attackers can spoof domains and replicate login pages with near-perfect accuracy.
Passkeys offer a systemic advantage in this scenario. Through cryptographic origin binding, the key is firmly tied to the authentic domain. The browser automatically checks whether the requesting domain matches the registered one. A phishing site on `m0bileid.ch` cannot access a Passkey registered for `mobileid.ch`. This makes Passkeys the first choice for pure web logins.
Important: Passkeys are not free from attack vectors either. Malware on the platform, compromised browser extensions or social engineering at the operating system level can affect any method. Passkeys specifically eliminate the URL spoofing problem.
### Closed Journeys: VPN, Remote Desktop, Kiosk, Native Apps
For logins via VPN clients, remote desktop/VDI environments, kiosk terminals, native app-to-app transitions or helpdesk callbacks, other protection mechanisms apply. In these scenarios there is no freely chosen URL. The connection is controlled by the client or the infrastructure. URL spoofing is not an attack vector.
Mobile ID SIM and App provide strong security here through hardware binding (EAL5+), geofencing, number matching and transaction signing. Passkeys are often not usable in many of these scenarios: WebAuthn is a browser technology, and VPN clients or remote desktop sessions (no BLE channel to the authenticator!) frequently do not support them.
### SIM and App Also Usable in the Browser
SIM and App can also be used for browser logins. Not every use case requires maximum phishing resistance in the browser. For many applications, the proven push-based authentication via SIM or App is a pragmatic and secure solution. Mobile ID covers all scenarios with OIDC and REST API.
## Why SIM and App Remain Indispensable
Passkeys are a strong addition for browser scenarios. SIM and App leverage their unique strengths where WebAuthn reaches its limits.
### Mobile ID SIM
The SIM-based method uses the Mobile ID enabled SIM card (or eSIM) as a secure hardware token. Over 6 million Swiss SIM cards from Swisscom, Sunrise, UPC and Salt are Mobile ID enabled. The cryptographic keys are stored directly on the SIM, which is certified under the protection profile **EAL5+** (ISO/IEC 15408) and Evaluation Level E3 (ITSEC).
The SIM method requires no app installation and has no app store dependency. The authentication prompt is displayed as a SIM Toolkit overlay directly on top of the business application. It works on any mobile device, including devices without a smartphone operating system, and over the GSM channel. Via SMS-over-IP and WiFi, the SIM method is also usable when there is no cellular connection.
When switching devices, the user simply moves the SIM. The account remains intact, without re-registration. SIM-based location verification is particularly trustworthy because the position within the mobile network is difficult to manipulate.
### Mobile ID App
The Mobile ID App (iOS and Android) offers, alongside biometric authentication, a broad range of additional capabilities that cannot be replicated with Passkeys:
**Push-based authentication** with biometrics or passcode as the second factor. **Geofencing** with GPS-based location determination and built-in jailbreak and mock service detection, making GPS spoofing more difficult. **Number matching**, where the user confirms a number displayed on screen within the app. **Transaction signing**, which displays transaction details (e.g. "Confirm the transfer of CHF 1,000 to account XY") directly on the device and requires the user's explicit consent. App-to-app transitions enable automated switching between the business application and the Mobile ID App and back in banking scenarios.
The app is based on technology from Futurae (ETH Zurich spin-off) and uses the device's Trusted Execution Environment (TEE). It is available worldwide in approved countries via the App Store.
## Passkeys-Plus: The Hybrid Auth Flow for Near AAL3
NIST AAL3 is an extremely high security standard. True AAL3 requires, among other things, a FIPS 140-2 validated hardware module, which depends on the specific device configuration. For highly critical systems, Swisscom already uses the **Passkeys-Plus** model internally, which targets a very high security level.
The approach combines two already existing components into a Hybrid Auth Flow:
**Step 1: Cloud-Sync Passkey (AAL2).** The user authenticates in the browser with a Passkey. This provides broad ecosystem support and phishing-resistant origin binding.
**Step 2: Mobile ID Push Step-Up.** The user then receives a push notification on their smartphone. Mobile ID Push uses public-key cryptography with non-exportable, device-bound keys. The user confirms with biometrics or passcode. Geoblocking and user consent display are optionally added.
The combination delivers: origin-bound login plus device-bound, non-exportable key plus explicit user consent plus geolocation. This can reach AAL3 in deployments where the second factor runs on suitable FIPS 140-2 certified hardware. Whether it is recognized as full AAL3 in every regulatory context must still be assessed per use case, hardware basis and compliance framework. Broader FIPS-validated cryptography and device attestation coverage in the Mobile ID Push step will only be fully available after future enhancements.
The push step remains on the smartphone. On desktop, the user authenticates locally with the Passkey, and the step-up occurs out-of-band via the phone.
## Mobile ID Authentication Levels: Granular Control via ACR Values
Alongside the NIST AAL framework described above, Mobile ID defines its own Authentication Levels (AL2–AL4) as ACR values in the OIDC Authorization Request. These levels control which authentication methods are permitted for a given login and should not be confused with NIST AAL1–AAL3. The full ACR matrix is documented in the [OIDC Integration Guide](/oidc-integration-guide/getting-started#authentication-context-class-reference-acr).
In `mid_al4_passkey` mode, a Passkey-only authentication is enforced, guaranteeing true phishing resistance without weak fallbacks. For maximum flexibility, `mid_al2_any` allows all available methods including SMS. With `mid_al4_any`, Passkey authentication is preferred with a fallback to SIM or App.
While most providers offer Passkeys only as a simple password replacement with insecure recovery paths (Google, PayPal, GitHub and even SBB allow OTP email as a fallback), Mobile ID enables the enforcement of strict security policies and the restriction to FIPS-certified authenticators via AAGUID validation against the FIDO Metadata Service database.
## Registration and Login Flows
The technical rollout is straightforward for Relying Parties.
### Centralized Registration on mobileid.ch
Users manage their Passkeys via the MyMobileID Dashboard on mobileid.ch/login. There they can add new keys, edit existing ones or delete them. The Passkeys are stored on the domain m.mobileid.ch and are subsequently available across all connected Relying Parties.
The registration process:
1. Login on mobileid.ch (verification via SMS OTP to confirm the mobile number).
2. Select the "Mobile ID Passkey" tile on the dashboard and click "MANAGE PASSKEYS".
3. Select "Add a passkey". The native browser dialog appears (Touch ID, Face ID or Security Key).
4. Biometric confirmation or PIN entry on the authenticator.
5. The Passkey is registered and receives a unique KeyRingID.
The KeyRingID (e.g. MIDPK5VQ8JV1TGL) is the stable identifier of a Passkey registration. For high-assurance scenarios (AL4), the Relying Party must pass this KeyRingID in the login_hint so that Mobile ID can verify the correct Passkey binding.
In Passkey management, the user sees all registered Passkeys with type labels: device-bound keys show a star badge, cloud-synced keys show "Synced" and "StepUp" badges. Each entry displays the KeyRingID, the creation date and the last usage.
1. The RP redirects the user to Mobile ID, with the desired ACR value in the Authorization Request.
2. Mobile ID displays the Passkey authentication page ("Passkey or FIDO2 Security Key").
3. The native browser dialog appears: "Sign in to mobileid.ch with your passkey".
4. The user confirms via biometrics or security key.
5. Mobile ID validates the assertion and redirects back to the RP with an authorization code.
6. The RP exchanges the code for an ID token and access token.