From 7149ddf7a3d7b97f4748dbb8e04d65346c81624e Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Mon, 4 Nov 2024 12:02:26 +0100 Subject: [PATCH 01/11] Proposed text that removes "WiFi is out of scope" and proposed operator token to be used on e.g. WiFi --- code/API_definitions/number-verification.yaml | 34 ++++++++++++++----- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 886ae34..c1a3e0a 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -9,18 +9,28 @@ info: # Introduction - Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service, where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope) either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves. - - It uses direct mobile network connections to verify possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. + Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service. + If the mobile device is accessing the *service provider* over a mobile network either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves. + If the mobile device is accessing the *service provider* over a non-mobile network like e.g. WiFi then the API consumer needs to provide an operator token as the value of the OIDC authorization code flow parameter `login_hint`. + Please see the CAMARA-Security-Interoperability.md on the format of the login_hint value for operator tokens. + + How an operator token is obtained is outside the scope. + + The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. + There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. + It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. # Relevant Definitions and Concepts - **Network-Based Authentication**: Authentication mechanism based on the identification of the endpoint of a network connection. Network operators know to which subscriber a network resource is assigned at a given moment, for example the mobile phone number associated to a specific mobile network connection. + - **Operator Token**: Authentication mechanism based on [EAP-AKA](https://datatracker.ietf.org/doc/html/rfc5448). + # API Functionality - This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope). This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves. + This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service. + This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves. # Resources and Operations overview This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (**excluding** for example by SMS/OTP or user/password as an authentication method): @@ -36,7 +46,8 @@ info: **Additional details:** - - **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication via mobile network and without the user being involved. the use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction. + - **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. + So it is required to be authentication without the user being involved. The use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction. - **(2):** The way in which the phone_number is retrieved depends on the implementation. For example, access token may be a self contained encrypted JWT, so API can decrypt and identify phone_number. Some other implementations might request the phone_number associated to the token from Authserver. @@ -46,12 +57,19 @@ info: Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. - It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. + It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. + This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. - In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication. + In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. + The API client must authenticate on behalf of a specific user to use this service. # Further info and support - [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/). + [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. + For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/). + + [Operator Token TS.43 Service Entitlement Configuration](https://www.gsma.com/newsroom/gsma_resources/ts-43-service-entitlement-configuration/) + [Operator Token Authorisation Sever – Authenticator Capabilities Group](https://www.gsma.com/newsroom/gsma_resources/asac-01-v1-0/) + version: 1.0.0 x-camara-commonalities: 0.4.0 license: From ac304fa7ee0055f86307277e0a313541a8c08fbc Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Mon, 4 Nov 2024 16:02:27 +0100 Subject: [PATCH 02/11] remove blanks on empty line --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index c1a3e0a..11a064f 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -13,7 +13,7 @@ info: If the mobile device is accessing the *service provider* over a mobile network either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves. If the mobile device is accessing the *service provider* over a non-mobile network like e.g. WiFi then the API consumer needs to provide an operator token as the value of the OIDC authorization code flow parameter `login_hint`. Please see the CAMARA-Security-Interoperability.md on the format of the login_hint value for operator tokens. - + How an operator token is obtained is outside the scope. The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. From 5c35b39ee15cdfcc8ed42cc918d668a5bdb95441 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:24:29 +0100 Subject: [PATCH 03/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 11a064f..976aa8c 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -16,7 +16,7 @@ info: How an operator token is obtained is outside the scope. - The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. + The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. From 72065dae9f4ef691e11e7b1b3e253e990d68f3eb Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:24:42 +0100 Subject: [PATCH 04/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 976aa8c..d70d38e 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -15,7 +15,7 @@ info: Please see the CAMARA-Security-Interoperability.md on the format of the login_hint value for operator tokens. How an operator token is obtained is outside the scope. - + The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. From 40e16b74e42d58e2e636b5e6bb42d11fd83f5ff5 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:24:57 +0100 Subject: [PATCH 05/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index d70d38e..8c41c1f 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -17,7 +17,7 @@ info: How an operator token is obtained is outside the scope. The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. - There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. + There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. From e3b20b569a8e9bc3e765710f640790b886f2f387 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:25:11 +0100 Subject: [PATCH 06/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 8c41c1f..8bd453b 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -29,7 +29,7 @@ info: # API Functionality - This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service. + This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service. This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves. # Resources and Operations overview From 41df07225b798d002ee1ce5814b77a76fea06226 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:25:22 +0100 Subject: [PATCH 07/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 8bd453b..b971efd 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -46,7 +46,7 @@ info: **Additional details:** - - **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. + - **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication without the user being involved. The use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction. - **(2):** The way in which the phone_number is retrieved depends on the implementation. For example, access token may be a self contained encrypted JWT, so API can decrypt and identify phone_number. Some other implementations might request the phone_number associated to the token from Authserver. From 940fc33368795e837ae1a4437bc07f2df9d6c265 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:25:33 +0100 Subject: [PATCH 08/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index b971efd..4ef6929 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -57,7 +57,7 @@ info: Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. - It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. + It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. From 3272469bfef8a19ffd2d4b47229a5bdf6793b3c4 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:25:46 +0100 Subject: [PATCH 09/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 4ef6929..b89f29c 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -60,7 +60,7 @@ info: It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. - In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. + In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. # Further info and support From 29b30177a6446e092e6354d4a00a6b8d2ac55307 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 08:26:04 +0100 Subject: [PATCH 10/11] remove trailing blanks Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index b89f29c..ffdb82e 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -64,7 +64,7 @@ info: The API client must authenticate on behalf of a specific user to use this service. # Further info and support - [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. + [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/). [Operator Token TS.43 Service Entitlement Configuration](https://www.gsma.com/newsroom/gsma_resources/ts-43-service-entitlement-configuration/) From 7fc75734ccf9f4d6d634f7323f7ae5e7fd521dbf Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 5 Nov 2024 09:11:17 +0100 Subject: [PATCH 11/11] remove trailing blanks Sorry, the github editor introduces blanks which the user cannot see. --- code/API_definitions/number-verification.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index ffdb82e..e6cf183 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -15,7 +15,7 @@ info: Please see the CAMARA-Security-Interoperability.md on the format of the login_hint value for operator tokens. How an operator token is obtained is outside the scope. - + The NumberVerification API verifes possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. @@ -69,7 +69,7 @@ info: [Operator Token TS.43 Service Entitlement Configuration](https://www.gsma.com/newsroom/gsma_resources/ts-43-service-entitlement-configuration/) [Operator Token Authorisation Sever – Authenticator Capabilities Group](https://www.gsma.com/newsroom/gsma_resources/asac-01-v1-0/) - + version: 1.0.0 x-camara-commonalities: 0.4.0 license: