From 60fb59f3d28a95beb546a02558702d51349f6180 Mon Sep 17 00:00:00 2001 From: o749213 Date: Mon, 23 Jan 2023 16:17:06 +0100 Subject: [PATCH] reshaping the content (+readme.md update) --- .../CAMARA}/NUMBER_VERIFICATION_API.md | 0 .../{ => CAMARA}/number_verification.yaml | 0 .../MobileConnect/MC_VERIFIED_MSISDN.md | 4 +- .../{ => MobileConnect}/numberVerify.yaml | 0 documentation/API_documentation/README.MD | 84 +++++++++++++++++++ .../assets/docs/(placeholder4MCspec).docx | 0 6 files changed, 86 insertions(+), 2 deletions(-) rename {documentation/API_documentation => code/API_definitions/CAMARA}/NUMBER_VERIFICATION_API.md (100%) rename code/API_definitions/{ => CAMARA}/number_verification.yaml (100%) rename documentation/API_documentation/API_definition.md => code/API_definitions/MobileConnect/MC_VERIFIED_MSISDN.md (98%) rename code/API_definitions/{ => MobileConnect}/numberVerify.yaml (100%) create mode 100644 documentation/API_documentation/README.MD delete mode 100644 documentation/API_documentation/assets/docs/(placeholder4MCspec).docx diff --git a/documentation/API_documentation/NUMBER_VERIFICATION_API.md b/code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md similarity index 100% rename from documentation/API_documentation/NUMBER_VERIFICATION_API.md rename to code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md diff --git a/code/API_definitions/number_verification.yaml b/code/API_definitions/CAMARA/number_verification.yaml similarity index 100% rename from code/API_definitions/number_verification.yaml rename to code/API_definitions/CAMARA/number_verification.yaml diff --git a/documentation/API_documentation/API_definition.md b/code/API_definitions/MobileConnect/MC_VERIFIED_MSISDN.md similarity index 98% rename from documentation/API_documentation/API_definition.md rename to code/API_definitions/MobileConnect/MC_VERIFIED_MSISDN.md index 7a99f22..f50fa24 100644 --- a/documentation/API_documentation/API_definition.md +++ b/code/API_definitions/MobileConnect/MC_VERIFIED_MSISDN.md @@ -1,7 +1,7 @@ # Reference Number Verify API is based on Mobile Connect Verified MSISDN standardized product: -[IDY.54](assets/docs/(placeholder4MCspec).docx) +[IDY.54](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) **IDY.54 Mobile Connect Verified MSISDN Definition and Technical Requirements** @@ -65,7 +65,7 @@ Because Mobile Connect Verified MSISDN requires the use of the mobile data netwo - The SP educates the User about the need to perform number verification whenever the User attempts to login in the future. The SP provides further details such as revocation mechanism in a linked page (shown as “Learn more”). - The User is asked to provide long-lived consent to the SP. The use of data needs to be clearly stated in terms of the service and the privacy policy. -![Figure 1 - Mobile Connect Verified MSISDN Service Flow](./assets/images/figure1.png) +![Figure 1 - Mobile Connect Verified MSISDN Service Flow](/NumberVerification/documentation/API_documentation/assets/images/figure1.png) The service flow is as follows: diff --git a/code/API_definitions/numberVerify.yaml b/code/API_definitions/MobileConnect/numberVerify.yaml similarity index 100% rename from code/API_definitions/numberVerify.yaml rename to code/API_definitions/MobileConnect/numberVerify.yaml diff --git a/documentation/API_documentation/README.MD b/documentation/API_documentation/README.MD new file mode 100644 index 0000000..798eaa3 --- /dev/null +++ b/documentation/API_documentation/README.MD @@ -0,0 +1,84 @@ +# Number Verify API documentation + +## Overview + +### Introduction + +CAMARA Number Verify API aims to deliver proof of device possession, that is attached to SIM card and MSISDN, using mobile network authentication. + +CAMARA community agreed to enable Number Verify API in two complementary flavours: + +1. Based on CAMARA standardization guidelines, that enables API service on a dedicated endpoint and follows CAMARA AuthN/AuthZ concept. [More details available here](#details) +2. Based on GSMA Mobile Connect standardized family of Identity APIs, that delivers Verified MSISDN service. [More details available here](#details) + +### Quick start + +1. Download one of yaml files. +2. Contact CAMARA API maintainers to get guidance on the onboarding process: + + * [Deutsche Telekom - Dawid Wróblewski](https://github.com/DT-DawidWroblewski) + * [Telefonica - Mona Mokhber](https://github.com/monamok) + * [Orange - Ludovic Robert](https://github.com/bigludo7) + +### Onboarding process for Mobile Connect + +1. Describe your Use case within *Use Case Declaration Form* - provided by MNO employee that guides you through the whole process. MNOs require you to provide data like (it is a subject to local market/MNO conditions what is required): + +* Name/Address/Website/Contact +* Business Type +* Mobile Connect product that is required for a use case +* Use case description, from the consumer point of view (preferably with screenshots, sequence diagrams, and information about where Mobile Connect product shall be used) +* Purpose - the reason for using Mobile Connect +* Privacy Policy details +* Consent Policy details, including the process of consent acquisition + +2. Register *redirect_uri* +3. Register MSISDNs you would like to test Number Verify API +4. Register MSISDN to pass secrets (e.g. client_secret or API-key) + +Upon successful onboarding following details are shared: + +1. **client_id** - used for requesting Mobile Connect services +2. **client_secret** - passed in a secured way, e.g. by SMS to MSISDN provided during onboarding + +## Authentication and/or Authorization + +[Camara AuthN/AuthZ Concept]() +[Mobile Connect AuthN/AuthZ Concept covered within MC 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) + +## Documentation + +### Details + +|Flavour|Details Page| +|---|---| +|CAMARA|[DetailsPage](/NumberVerification/code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md)| +|Mobile Connect|[DetailsPage](/NumberVerification/code/API_definitions/MobileConnect/MC_VERIFIED_MSISDN.md)| + +### Endpoint definitions + +|Flavour|Endpoint type|Endpoint path| +|---|---|---| +|CAMARA|AuthN/AuthZ|| +||resource|/verify| +|Mobile Connect|AuthN|/authorize
/token| +||resource|/userinfo| + +>Please note that Mobile Connect **/authorize** covers mobile network authentication step that requirements are subject of a particuler MNO and might require, but not limited to, e.g. additional request headers, request in HTTP, follow redirect to additional ID services (like token servers). + +### Errors + +Described inside yaml files. + +### Release Notes + +|No|Version|Changelog| +|:---:|---:|:---| +|1|0.5.0|Camara & Mobile Connect flavours available| + +## API Spec + +|Flavour|yaml| +|---|---| +|CAMARA Number Verification|[yaml](../../code/API_definitions/CAMARA/number_verification.yaml)| +|Mobile Connect Verified MSISDN|[yaml](../../code/API_definitions/MobileConnect/numberVerify.yaml)| diff --git a/documentation/API_documentation/assets/docs/(placeholder4MCspec).docx b/documentation/API_documentation/assets/docs/(placeholder4MCspec).docx deleted file mode 100644 index e69de29..0000000