Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document when FE flow is applicable with regards to involved devices #256

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Document when FE flow is applicable with regards to involved devices #256

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
235b570
Update CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Jan 31, 2025
c55cebf
Update CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Jan 31, 2025
b26eb5b
Update CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Jan 31, 2025
0572372
Update CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Jan 31, 2025
5813965
Update CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Jan 31, 2025
e0b5efe
Update documentation/CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Feb 12, 2025
cc4cfbe
Update documentation/CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Feb 12, 2025
c92703c
Update documentation/CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Feb 12, 2025
fd508c1
Update documentation/CAMARA-API-access-and-user-consent.md
Elisabeth-Ericsson Feb 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions documentation/CAMARA-API-access-and-user-consent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ The list below introduces several key concepts:
- `Resource Server`: the server that exposes protected resources to Applications. The Resource Server requires a valid access token to be provided before allowing access to the protected resource.
- `Scope`: the OpenID Connect scope which maps one or more protected resources, some scopes may require processing of Personal Data.
- `Subscriber`: the mobile subscriber of the Operator. The Subscriber is usually also the End-User, but this is not always the case. For example, a parent may be the Subscriber of a mobile subscription for their child, the End-User.
- `Target Device`: the device that is the primary resource (target) affected by an API call, and for which Consent may need to be obtained from the Resource Owner.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should also add a definition of an Authentication Device. The one in the CIBA standard looks good to me:

The device on which the user will authenticate/authorize the request, often a smartphone.
Ref: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#terminology

- `Three-Legged Access Token`: an access token that involves three parties: the Resource Owner (User), the Authorization Server (operated by the Operator or Aggregator), and the client (the ASP's Application). In CAMARA, Three-Legged Access Tokens are typically created using the OIDC Authorization Code flow or Client-Initiated Backchannel Authentication (CIBA) flow.
- `Two-Legged Access Token`: an access token that involves two parties, the Authorization Server (operated by the Operator or Aggregator), and the client (the ASP's Application); the Two-Legged Access Token does not include a Resource Owner (User). The Authorization Server does not autenticate a User, nor can User Consent be captured or validated for Two-Legged Access Tokens; therefore Two-Legged Access Tokens must only be used for CAMARA APIs that do not process Personal Data.

Expand All @@ -84,6 +85,7 @@ This section describes the authorization flows that can be used to access CAMARA
Note: In cases where Personal Data is processed by a CAMARA API, and Users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of Three-Legged Access Tokens is mandatory.

#### Authorization Code Flow (Frontend Flow)
The Authorization Code Flow is only applicable if the Consumption Device that initiates the process of obtaining a Three-Legged Access Token from the Authorization Server is also the Target Device of the intended CAMARA API call(s).
Comment on lines 87 to +88
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The applicability of the Authorization Code Flow is described in the Technical ruleset for the Frontend flow section. It may be better to move this statement there and integrate it with the rest of the information in that section here

Something like...

If all API use cases indicate the need for an 'On-Net' scenario and where the Consumption Device and Authentication Device are the same, the Front-end flow (Authorization Code Flow) SHOULD be used. e.g. Number Verification API.

Also note, the Authorization Code Flow is only applicable if the Consumption Device that initiates the process of obtaining a Three-Legged Access Token from the Authorization Server is also the Target Device of the intended CAMARA API call(s). Therefore, access tokens are issued for the network authenticated identifier.

This flow then enables On-Net scenarios where the mobile connection of the Consumption Device needs to be authenticated. For example, the [CAMARA Number Verification API](https://github.com/camaraproject/NumberVerification), due to the nature of its functionality, where the User's MSISDN needs to be compared with the MSISDN associated with the mobile connection of the Consumption Device.


```mermaid
sequenceDiagram
Expand Down Expand Up @@ -180,12 +182,14 @@ The Application on the Consumption Device must be able to handle browser redirec
- Check if User Consent is required as the lawful basis associated with the declared Scope and Purpose.
- If necessary, it will be checked in the operator's consent master whether user consent has already been given to the application for the user identifier and declared purpose.
- If NOT granted, the operator performs the consent capture. Since the authorization code grant involves the interaction with application front-end, consent can be captured directly from the user through the application browser.
- Covered scenarios:
- Covered scenarios:
- On-net (with mobile connection) & application front-end (with embedded browser)
- Off-net scenarios using refresh_token, as long as there was a connection when the first access_token was requested.
- Note: The Consumption Device must be equal to the Target Device of subsequent API call(s).


#### CIBA flow (Backend flow)
The CIBA flow is applicable if the Consumption Device is equal to or different from the Target Device of the intended CAMARA API call(s).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CIBA is necessary if Consumption Device and Authentication Device are different. If Consumption Device and Authentication Device are the same, then OIDC Authentication Code Flow SHOULD be used.

The API Provider MUST send a message to the authentication device, identified by login_hint, because otherwise there would be no authentication at all.

Note: In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

User consent cannot be checked based on the login_hint value alone and without sending a message, because then CIBA would be a two-legged flow while according the the note above a three-legged flow is mandatory.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Relation between consumption device and authentication device:

CIBA is necessary if Consumption Device and Authentication Device are different. If Consumption Device and >Authentication Device are the same, then OIDC Authentication Code Flow SHOULD be used.

The API invoker cannot know whether consumption device and authentication device are different. The API invoker in general has no awareness at all about authentication devices. The API invoker only knows the target device and potentially also the consumption device. Who is the legal responsbile (authorization device) of the target device is only known to the backend - the telco operator.

The OIDC Authentication Code Flow protocol does not foresee to communicate whether the consumption device is the authentication device or not. It would be beneficial to get this information in the response, but this is not the case today.

CIBA flow:

User consent cannot be checked based on the login_hint value alone and without sending a message, because then >CIBA would be a two-legged flow while according the the note above a three-legged flow is mandatory.
Can you please clarify this statement ?
AFAIK CIBA transports the information about the target resource/target device in the login_hint, The consent check happens for the target resource specified in the login_hint, The API invoker does not have any knowlege about the consumption device in this context.

Comment on lines 191 to +192
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The applicability of the CIBA Flow is described in the Technical ruleset for the Backend flow section. It may be better to move this statement there and integrate it with the rest of the information in that section here

Something like...

If the API use case(s) indicate the need for an "Off-net" scenario and/or if the Consumption Device and Authentication Device are different, the Backend flow (CIBA) SHOULD be used.

Also note that in the case of the CIBA flow, it is applicable if the Consumption Device is the same or different from the Target Device of the intended CAMARA API call(s).


```mermaid
sequenceDiagram
Expand Down Expand Up @@ -282,12 +286,13 @@ If some use case(s) for an API point to "Off-net" scenarios and where Consumptio
- Check if user consent is required by lawful basis associated with the declared purpose.
- If necessary, it will be checked **in the operator's consent master** whether user consent has already been given to the application for the user identifier and declared purpose.
- If NOT granted, **the operator’s consent capture procedure is triggered**. Out-of-band consent capture as part of asynchronous CIBA flow (e.g. push notification with fallback to SMS, etc...). **Operators can choose the consent capture mechanism that best suits their capabilities, preferences and needs**.
- Covered scenarios:
- Covered scenarios:
- No front-end developer software in user device
- Back-end services (e.g. bank BE anti-fraud validation using MSISDN).
- Off-net scenarios (no mobile connection)
- Device connected to WiFi
- Device without UI (IoT)
- Note: Consumption device and target device of subsequent API call(s) can be different, access token is generated for the target device

#### Client Credentials

Expand Down