Include readiness Checklist and User Stories proposal for SIM Swap #125
Conversation
jgarciahospital
requested review from
bigludo7 and
fernandopradocabrillo
as code owners
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users. <br> **Scope:** <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:BusinessManager has successfully subscribed to the SIM Swap API product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| | ||
| | ***Activities/Steps*** | **Starts when:** The customer application makes a POST request to the /retrieve-date endpoint via the SIM Swap API, including the phone number provided by the user in the application.<br>**Ends when:** The SIM Swap server responds with the timestamp of the last SIM swap event, or the SIM activation date if no swap has occurred. | | ||
| | ***Post-conditions*** | The customer application could continue offering its service to the user with the confirmation of the validity of the SIM based on the SIM Swap information. | |
There was a problem hiding this comment.
Roles section must also introduce "the user" mentioned here
| | **Item** | **Details** | | ||
| | ---- | ------- | | ||
| | ***Summary*** | As an enterprise application developer, I want to verify the last SIM Swap date for a user's mobile number so that I can enhance security measures against account takeover fraud. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users. <br> **Scope:** <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. | |
There was a problem hiding this comment.
Actors can play different roles, so roles and actors are not exclusive. One need to guess which actor plays which role.
Customer:BusinessManager is most propably a human, while Customer:User (according to the seteps) is most probably a machine user. Can we make extent the US with an example?
There was a problem hiding this comment.
What we have in mind (maybe clarification can be included in the text):
-
Roles: specifies the role(s) that the CAMARA API customer plays for the user story. Options -> customer:user; customer:administrator; customer:business manager.
-
Actor(s): API usage should not be restricted to a particular actor (e.g., application service provider, hyperscaler, application developer, or end user where e.g. consent is required). Examples may use a particular actor to perform a role in the API flow, but that does not exclude other Actors from performing the role.
There was a problem hiding this comment.
Who is "CAMARA API customer", this sounds like a role by itself?
You are right that different actors can play the same role - this is the purpose of the roles and the reason why logic must be roles based, not actors based. And MNO itself plays some role as well. Without that one cannot describe a flow.
Listed actors already looks like roles:"hyperscaler" - is a role, which many companies do play. And if a "hyperscaler" wants to call simswap towards my data, it, most probably, acts as an application service provider (provides some service to me), not as a hyperscaler. Why hyperscaler and application service provider, but banks do not.
Suggestion: describe the whoe US in pure roles terms. Give an example or two of two, which shows how different actors can play different roles.
BTW, can you explain what role an end-user can play in sim swap US?
There was a problem hiding this comment.
Just aligning with other US like NV, I'd propose:
- Include CSP as SIM Swap server owner, generic as not binded to MNO (even when in this API it's clear)
- Maintain current actors as aligned with NV. Since actor can be from the proper producer (CSP) to the consumer (ASP,dev) or a indirect consumer (hyperscaler), it still makes sense.
End-user on the other side only makes sense as users of the app, as in the final step. I'll update it with end-user instead of only user.
| | **Item** | **Details** | | ||
| | ---- | ------- | | ||
| | ***Summary*** | As an enterprise application developer, I want to verify the last SIM Swap date for a user's mobile number so that I can enhance security measures against account takeover fraud. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users. <br> **Scope:** <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. | |
There was a problem hiding this comment.
Actors: Application service providers, hyperscalers, application developers, end users.
Why mention them here if they are not used in the US?
There was a problem hiding this comment.
As interchangeable parties who can take part in the flow. User is just an example.
| | ---- | ------- | | ||
| | ***Summary*** | As an enterprise application developer, I want to verify the last SIM Swap date for a user's mobile number so that I can enhance security measures against account takeover fraud. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users. <br> **Scope:** <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:BusinessManager has successfully subscribed to the SIM Swap API product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| |
There was a problem hiding this comment.
Access token is a pre-requisite. It looks like the US explicitly describes client-credentials flow
There was a problem hiding this comment.
Both options are of course allowed, but both options are a prerequisite not part of the proper API call process. Whether the token identifies the user whose data is accessed or only identifies developer's
There was a problem hiding this comment.
"The Customer:User has the access token allowing a secure access of the API." sounds like the access token is API level, not phoneNumber level.
Could it make sense to adjust the text to:
"The Customer:User has the access token allowing a access of the API and sim swap information of the target phoneNumber"?
There was a problem hiding this comment.
OK, but including a "if applies" just because the binding of the token to the phone number is only for the 3-legged cases.
| | ***Summary*** | As an enterprise application developer, I want to verify the last SIM Swap date for a user's mobile number so that I can enhance security measures against account takeover fraud. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users. <br> **Scope:** <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:BusinessManager has successfully subscribed to the SIM Swap API product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| | ||
| | ***Activities/Steps*** | **Starts when:** The customer application makes a POST request to the /retrieve-date endpoint via the SIM Swap API, including the phone number provided by the user in the application.<br>**Ends when:** The SIM Swap server responds with the timestamp of the last SIM swap event, or the SIM activation date if no swap has occurred. | |
There was a problem hiding this comment.
The US must use earlier defined roles and actors here. Customer application (must be listed as actor) acts as Customer:User here (otherwise its request will be rejected).
SimSwap Server must be as an actor
There was a problem hiding this comment.
Let's include CSP directly as actor.
| | ***Summary*** | As an enterprise application developer, I want to verify the last SIM Swap date for a user's mobile number so that I can enhance security measures against account takeover fraud. | | ||
| | ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users. <br> **Scope:** <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. | | ||
| | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:BusinessManager has successfully subscribed to the SIM Swap API product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.| | ||
| | ***Activities/Steps*** | **Starts when:** The customer application makes a POST request to the /retrieve-date endpoint via the SIM Swap API, including the phone number provided by the user in the application.<br>**Ends when:** The SIM Swap server responds with the timestamp of the last SIM swap event, or the SIM activation date if no swap has occurred. | |
There was a problem hiding this comment.
"or the SIM activation date if no swap has occurred" is implementation specific, as far as I can remember it was clarified that exposing events older than 60 days does not comply with GDPR.
The US in general is written a super generic language, I would suggest to avoid using statements which are depends on local regulation in it.
There was a problem hiding this comment.
Taking regulation out, the API clearly states that the activation date is considered as a swap, independently of this data been able to be provided or not depending on the regulation. In a nutshell, and generally, if the regulation allows, activation date will be provided as sim swap event if no other proper sim swap occured.
There was a problem hiding this comment.
yes, time frame limitation, you are right.
BTW, one can implement limited time frame for technical reason only. Like why dig into 20 years history for a fraud prevention API where the attack window is a week at best.
There was a problem hiding this comment.
In such case it is supposed to be considered as an error, not sure if we need to include that in the user story.
What type of PR is this?
What this PR does / why we need it:
Including Checklist for SIM Swap API (both endpoints) and the API readiness checklist.
Which issue(s) this PR fixes:
Fixes #123