Repository navigation
Functionality to support B2B2C and B2C #180
Description
Activity
Some findings and observations derived from the B2B2C use-case. B2C can be seen as a special case of B2B2C, where the Network Provider is directly interacting with a consumer.
General observations:
- The Gaming Application Backend (BE) is running the CAMARA 3-legged AT procedure
- The Gaming BE obtains a target device identifier, either by asking the Gamer for its MSISDN or obtain a Public IP / port or may get some other device identification information. This identifier is then pass (as login_hint) into the 3-legged Access Token request procedure (together with the Gaming BE's access credentials).
- The AuthZ Server will then run the ICM procedure.
- The Gamer may not have API access credentials and may not be able to use any Service API. It is assumed the Gamer can access some self-service portal in case of access revocation.
- Accessing the API from the Gaming Application on the device (i.e. API Consumer on the device) sounds tempting, however, such setups are generally not recommended from security perspective. The Application BE would need to share API keys with the device, and such a procedure is not considered “secure”, specifically for browser based applications.
- In this Gaming scenario, that each device (visitor)) is owned/controlled by different users. From a scalability & performance perspective, it is fine for adding devices individually.
Suggestions
- The device object should not be a required object (i.e. should be optional), neither in request operations nor in response operations.
- There is no need for allowing public IP / port within the device object, since the device object should never be present in 3-legged token cases. Supporting only the phone number in case of B2B scenarios) can be ok.
Two open questions (potentially exam questions):
A: Is there a case / is there a gap for B2B2C, where two different API consumers (different owners) add devices for the same access (or create accesses for the same network)?
B: Would it be cleaner to create a new endpoint for managing a single device, i.e. creating an access with a single device and/or adding a single device to an existing access resource?
I created some call flows, focusing on B2B and B2B2C Scenarios and whether to use a 2-legged token or a 3-legged token for the different operations.
Towards the end, there is a section focusing on the above introduced Gaming scenario.
Highlighting key questions from the AccessesCallFlows.md up
Identified general aspects on 2-legged and 3-legged token usages
There are a number considerations when using 3-legged access tokens for the API access. In general, the subject is identified from the access token and not provided within the API body. Information encapsulated in the access token (i.e. info about the subject) is not disclosed to the API consumer.
-
The API consumer must decide on a 2-legged or 3-legged token usage. The API consumer should do this based on the relation to the targeted device. The "relation" means here, that the Network Provider is aware, that the API consumer and the device owner are in the same organization (i.e. have a relation) and that the Network Provider allows a 2-legged token usage for the given device(s).
- When there is no relation (i.e. device does not belong to the same organization as the API Consumer), a 3-legged token is used. This is a B2C or a B2B2C scenario.
- When the device belongs to the same organization as the API Consumer, the Network Provider should be aware about the relation. In this case, a 2-legged token can be used. Note, the Network provider may always verify the relation of the API consumer and the device owner. This is a B2B scenario.
- When the needed operation does not target a device, the API consumer can use a 2-legged access token. For example, when the API consumer uses the
areasor thenetworksAPI, the operation never requires a device identifier.
-
When a 3-legged token is used, the response must not contain any
deviceobject — device-identifying information provided via the token must not be disclosed. -
3-legged tokens can only be used for targeting one device at a time.
-
Operations that reference devices by an opaque, server-generated (resource) identifier can use a 2-legged token, even in B2B2C scenarios, because the identifier does not disclose device-identifying information. Such a resource must have been previously created using a 3-legged token by the same API consumer.
-
When a device specific resource has been created using 3-legged access tokens, the
deviceobject must not be present in any notification.
Applicable sequences from AccessesCallFlows.md to the Gaming Convention use-case
| Sequence | Applies? | Rationale |
|---|---|---|
| A1 — Create access (no devices) | Yes | The Gaming company creates an empty access before the event using a 2-legged token. |
| A2a — Create access with devices (2-legged, B2B) | No | The Gaming company does not manage visitor devices — this is B2B2C. |
| A2b — Create access with device (3-legged, B2B2C) | Possible | Could apply if the first visitor’s consent triggers access creation, but A1 + B2 is more natural for a pre-planned event. |
| B1 — Add devices (2-legged, B2B) | No | The Gaming company does not know or manage visitor phone numbers directly. |
| B2 — Add device (3-legged, B2B2C) | Yes — core flow | Each visitor authenticates and consents; their device is added one at a time via a 3-legged token. |
| C — Delete a single device | Yes | A specific visitor’s device can be removed using the opaque accessDeviceId. Uses 2-legged token. |
| D — Remove multiple devices | Yes | Batch removal at the end of a demo session or at event close. Uses 2-legged token. |
| E1a / E2a — List devices (B2B) | No | This is a B2B2C scenario; the B2B listing variant (with phone numbers) does not apply. |
| E1b / E2b — List devices (B2B2C) | Yes | The Gaming company checks device status. The device object (phone number) is not disclosed. |
| F1a / F1b / F1c — Notifications (B2B) | No | B2B notification variants (with device object) do not apply to this B2B2C scenario. |
| F2a — REQUESTED → GRANTED (B2B2C) | Yes | The Gaming company is notified when a visitor’s device is granted access. |
| F2b — REQUESTED → DENIED (B2B2C) | Yes | The Gaming company is notified if a visitor’s device is denied. |
| F2c — GRANTED → DENIED / revocation (B2B2C) | Yes | The Gaming company is notified if access is revoked mid-event. |
General Questions on Error Conditions
- Is the assessment correct, that a 2-legged access token can be used for "deleting a single device"? The operation would use the opaque
accessDeviceIdfor the deletion. - Should the API allow usage of a 3-legged access token for "deleting a single device"? When yes, this would lead to increase complexity in documentation and also implementation. The API provider would need to verify, whether the information from the access token matches the
accessDeviceIdinformation.
Updating the table from previous comment, adding a new column "2-legged in B2B2C?". When yes, then usage of 2-legged tokens is supported, even for B2B2C scenarios. When no, then the usage of 2-legged tokens is not allowed. When N/A, this row is not applicable for this analysis (i.e. either no token or a 2-legged token by scenario).
| Sequence | Applies? | 2-legged in B2B2C? | Rationale |
|---|---|---|---|
| A1 — Create access (no devices) | Yes | Yes | No device is addressed — 2-legged token suffices. |
| A2a — Create access with devices (2-legged, B2B) | No | N/A | Devices provided explicitly in body — inherently B2B. A 2-legged token with device identifiers requires a known B2B relationship. |
| A2b — Create access with device (3-legged, B2B2C) | Possible | No | Device is identified from the 3-legged token. A 2-legged token cannot identify the end user's device without disclosing it. |
| B1 — Add devices (2-legged, B2B) | No | N/A | Devices provided explicitly in body — inherently B2B. |
| B2 — Add device (3-legged, B2B2C) | Yes — core flow | No | Device is identified from the 3-legged token. The end user must authenticate and consent; a 2-legged token cannot substitute. |
| C — Delete a single device | Yes | Yes | Device is addressed by opaque accessDeviceId, not by a device identifier. Per the general rules, operations using opaque server-generated identifiers can use a 2-legged token in B2B2C. |
| D — Remove multiple devices | Yes | Yes | Same as C — devices addressed by opaque accessDeviceIds. |
| E1a / E2a — List devices (B2B) | No | N/A | B2B variant — not applicable to B2B2C. |
| E1b / E2b — List devices (B2B2C) | Yes | Yes | No device identifier in request. 2-legged token is used; the device object (phone number) must not appear in the response. |
| F1a / F1b / F1c — Notifications (B2B) | No | N/A | B2B variant — not applicable to B2B2C. |
| F2a — REQUESTED → GRANTED (B2B2C) | Yes | N/A | Server-initiated push notification — no consumer token involved in receiving it. The device object must not be present in the notification. |
| F2b — REQUESTED → DENIED (B2B2C) | Yes | N/A | Same as F2a — server-initiated, no consumer token. |
| F2c — GRANTED → DENIED / revocation (B2B2C) | Yes | N/A | Same as F2a — server-initiated, no consumer token. |
Observations
- Two operations must use a 3-legged token for B2B2C cases, since a device is directly addressed — namely A2b and B2.
- Multiple operations can allow using 2-legged tokens even for B2B2C cases (i.e. A1, C, D, E1b, E2b). However, should we allow using a 3-legged token, even when not needed?
The following table discusses how the API should behave if an API consumer uses a 3-legged token for operations where a 2-legged token would suffice:
| Operation | Potential Action, when a 3-legged token is used |
|---|---|
| A1 — Create access (no devices) | This operation cannot be used with a 3-legged token, it becomes an A2b case, i.e. Create access with device. |
| C — Delete a single device | The Service API needs to check whether the subject associated with the accessDeviceId is the same as the access token's subject. When not, the Service API throws a new 422 Error Code. |
| D — Remove multiple devices | A 3-legged token can only target one device at a time, so it cannot be used for batch removal. For single-device removal, use sequence C instead. The Service API should throw a new 422 Error Code. |
| E1b / E2b — List devices (B2B2C) | The Service API can use the identifier from the token as filter condition. However, this would be a redundant operation, since such filtering is possible using the accessDeviceId with a 2-legged token. Thus, better to throw an error. |
Another solution for preventing the usage of a 3-legged token is via the API scopes: The Authorization Server could disallow the usage of 3-legged access tokens for the listed operations. This would then generally lead to a 403 Error Code, thus, no new Error Code needed.
Problem description
The current set of Dedicated Network APIs primarily supports B2B scenarios in which the API consumer and the device using the dedicated network resources are managed by the same organization. This assumption does not cover B2B2C or B2C scenarios, where an API consumer provides a service to end users who access the network resources through their own devices.
To identify the required functionality, the workflow of a representative B2B2C use case should be analyzed.
Use Case: Gaming Demonstration at a Convention
A Gaming developer company wants to showcase a newly developed smartphone game at a gaming convention. Convention visitors are invited to install and test the game on their personal smartphones.
Because the game requires a stable and predictable network connection, the Gaming company rents dedicated connectivity resources from a public network provider for the duration of the event. These resources are intended to provide an appropriate network experience for visitors participating in the demonstration.
The Gaming company must then selectively authorize individual convention visitors to use the reserved network resources while they are taking part in the demonstration. The visitors use their own smartphones, and the Gaming Developer may not have a direct management relationship with either the devices or their subscribers.
In this scenario:
Problem Statement
The existing API functionality appears to focus on scenarios where the API consumer is also responsible for the devices using the dedicated network. Consequently, it is unclear whether the APIs support the delegation and lifecycle management required when a service provider authorizes third-party end users to access dedicated network resources.
The following questions should be addressed:
Additional context
The Gaming Backend needs to know, which ICM Flow to use, including DPoP.
Potentially, a separate EndPoint is needed for clean separation of 2-legged and 3-legged workflows.
Related Issue #139