Skip to content

Commit

Permalink
Phone number identification with 3Legs
Browse files Browse the repository at this point in the history
- Phone number identification with 3Legs, according to: camaraproject#51
FabrizioMoggio authored Jul 15, 2024
1 parent 2e3af7b commit 266a46c
Showing 1 changed file with 83 additions and 17 deletions.
100 changes: 83 additions & 17 deletions code/API_definitions/Call_Forwarding_Signal.yaml
Original file line number Diff line number Diff line change
@@ -7,17 +7,17 @@ info:
title: Call Forwarding Signal API
version: wip
description: |
## Overview
# Overview
The Call Forwarding Signal (CFS) API provides the API Consumer with
information about the status of the Call Forwading Service on a specific
phone number.The main scope of the CFS API is "anti Fraud" to avoid
fraudster to use the Call Forwarding Service to carry on a scam. Other use
phone number. The main scope of the CFS API is "anti Fraud" to avoid
fraudsters to use the Call Forwarding Service to carry on a scam. Other use
cases are anyway supported by the CFS API that also provides additional
endpoints to detect the general Call Forwarding Service settings.
## 1. Introduction
# Introduction
The Call Forwarding Service is provided by the Network to a phone
number. This service redirects the incoming call to that phone number
to an alternative destination such another phone number or a voice mail
to an alternative destination such as another phone number or a voice mail
system. There are two main types of call forwarding settings:
unconditional and conditional.
The CFS API can be invoked to detect if the unconditional
@@ -37,7 +37,7 @@ info:
\
[**Call Forwading Verification**](https://github.com/camaraproject/\
CallForwarding\Signal/discussions/3#discussioncomment-8915595)
## 2. Quick Start
# Quick Start
The CFS API is a REST API based on the CreateCallForwardingSignal resource.
This resource is filled during the API invokation, by the API Consumer,
with the phone number on which the Call Forwarding Service status must be
@@ -74,7 +74,7 @@ info:
active on a specific phone number?
- **call-forwardings**: Which is the status of the call forwarding for a
specific phone number?
## 3. Authorization and authentication
# Authorization and authentication
CAMARA guidelines defines a set of authorization flows which can grant API
clients access to the API functionality, as outlined in the document
[CAMARA-API-access-and-user-consent.md](https:\
@@ -84,7 +84,14 @@ info:
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.
framework dictated by local legislation.\
Specifically, for the CFS API, the CIBA flow should be adopted. The CIBA
flow is described here:[CIBA Flow](https://github.com/camaraproject/\
IdentityAndConsentManagement/blob/main/documentation/\
CAMARA-Security-Interoperability.md\
#client-initiated-backchannel-authentication-flow). The "login_hint" must be
the user's phone number valorised as the parameter PhoneNumber, if used. If
a mismatch is detected, a 403 error is returned (`INVALID_TOKEN_CONTEXT`).
\
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
@@ -93,12 +100,33 @@ info:
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.
## 4. API Documentation
## 4.1 Details
The CFS API is invoked by an API Consumer after the Consent Management flow
described in chapter 3.\
The API Consumer creates a resource (CreateCallForwardingSignal) containing
the phone number (PhoneNumber) to be checked.\
# Identifying the phone number from the access token
This specification defines the "phoneNumber" field as optional in API
requests because using a 3-legged access token the phone number can be
uniquely identified by the token.
## Handling of phone number information:
### Optional phone number object for 3-legged tokens:
When using a 3-legged access token, the phone number associated with the
access token must be considered as the phone number for the API request.
This means that the "phoneNumber" paramenter is not required in the request,
and if it is included it must identify the same phone number.
### Validation mechanism:
- The server will extract the phone number identification from the access
token, if available.
- If the API request additionally includes a "phoneNumber" parameter when
using a 3-legged access token, the API will validate that the phone number
identifier provided matches the one associated with the access token.
- If there is a mismatch, the API will respond with a
403 `INVALID_TOKEN_CONTEXT` error, indicating that the device information
in the request does not match the token.
### Error handling for unidentifiable devices:
- If the "phoneNumber" parameter is not included in the request and the
phone number information cannot be derived from the 3-legged access token,
the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.
# API Documentation
## Details
The CFS API is invoked by an API Consumer after the Consent Management
flow.\
The API Consumer can request the API Producer for the status of the
Unconditional Call Forwarding service using the
unconditional-call-forwardings POST method. A boolean, with the information
@@ -108,9 +136,13 @@ info:
the Call Forwarding service using the call-forwardings POST method. An array
of strings with the information of the type of active call forwarding
services will be provided back via the CallForwardingSignal resource.\
## 4.2 FAQ's
CFS API have to check the Call Forwarding
Service status can be optionally defined with resource
(CreateCallForwardingSignal) containing the phone number (PhoneNumber)
to be checked.
# FAQ's
(FAQs will be added in a later version of the documentation)
## 4.3 Release Notes
# Release Notes
First draft for the CFS API.
license:
name: Apache 2.0
@@ -189,6 +221,8 @@ paths:
$ref: "#/components/responses/Generic409"
"415":
$ref: "#/components/responses/Generic415"
"422":
$ref: "#/components/responses/Generic422"
"429":
$ref: "#/components/responses/Generic429"
"503":
@@ -242,6 +276,8 @@ paths:
$ref: "#/components/responses/Generic409"
"415":
$ref: "#/components/responses/Generic415"
"422":
$ref: "#/components/responses/Generic422"
"429":
$ref: "#/components/responses/Generic429"
"501":
@@ -397,7 +433,7 @@ components:
status: 403
code: INVALID_TOKEN_CONTEXT
message: PhoneNumber parameter doesn't match the value from the
acces token context
access token context
Generic404:
description: The specified resource was not found
headers:
@@ -459,6 +495,36 @@ components:
code: UNSUPPORTED_MEDIA_TYPE
message: The server refuses to accept the request because the
payload format is in an unsupported format.
Generic422:
description: Unprocessable Content
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
description: Inconsistency between device identifiers not pointing
to the same device
value:
status: 422
code: DEVICE_IDENTIFIERS_MISMATCH
message: Provided device identifiers are not consistent.
GENERIC_422_DEVICE_NOT_APPLICABLE:
description: Service is not available for the provided device
value:
status: 422
code: DEVICE_NOT_APPLICABLE
message: The service is not available for the provided device.
GENERIC_422_UNIDENTIFIABLE_DEVICE:
description: phone number not available neither from "phoneNumber"
or from the access token.
value:
status: 422
code: UNIDENTIFIABLE_DEVICE
message: phone number not defined
Generic429:
description: Too Many Requests
headers:

0 comments on commit 266a46c

Please sign in to comment.