Street Identity API model

Minimum IDP Tasks
1. Provide a place for a user to see the “display names” of their verified (or pending verification) street addresses and delete them.
  • If the address was pushed in by a complex AttributeProvider, then the name of that AP may also be listed.  The user may also be able to see in that same UI what RPs have access to those addresses with the ability to revoke them, or that might be shown elsewhere.
2. Expose a StreetIdentity API protected by a new OAuth scope to READ StreetIdentity
  • GetList - returns a list, possibly empty, of display names of verified street addresses, the identifier for the attribute provider for that address, as well as an index for that user to that specific street address.  A particular index is never reused.  Note that a very advanced IDP might let the user pick a subset of addresses to share with a specific RP.
  • GetAccessToken (index) - returns an access token that is a JWT signed by the IDP with a timestamp, the mailrecipient ID, a scope that represents streetidentity, and the OAuthClient to which it was issued, and an identifier for the attribute provider).
Minimum RP Tasks
1. Perform a standard OpenIDConnect or OAuth2 3LO request for that read-only StreetIdentity API scope
2. Use the GetList API to confirm a verified address is available, and get the index for it and the attribute provider
3. Use the GetAccessToken function to get a token for a specific address
4. Send it to the AttributeProvider’s GetAddress API via an OAuth2 request with the token from #3, and get back the user’s actual verified name/address or an error code

Minimum AttributeProvider Tasks
1. Expose a GetAddress API that requires an OAuth2 request with a token from an IDP.  In general it should return the name and address of the user in a PoCo/JSON type format.  However before returning it, the AP needs to check that:
  • The RP’s can be authenticated using it’s OAuth2 assertion, and this is a registered/trusted RP that the AP knows how to bill
  • The token’s signature can be verified as coming from an IDP that is trusted/certified
  • The timestamp is not too old
  • The attribute provider in the token is the same as the attribute provider who received the API call
  • The RP in the token is the same as the RP authenticated using the OAuth2 assertion
  • The scope in the token is the same as the scope the AP uses to control access to this API
  • The MailRecipient entry should list this IDP as either the one that initiated the flow (in the simple AP case), or where the IDP was the target of a 3LO request to the WRITE scope of the streetidentity API (in the complex AP case)

2. The AP will also need to setup a billing relationship with potential RPs, as well as agree to the TermsOfService for how the street identity can be used.  It is generally expected that APs will charge RPs the same amount no matter whether they were the first RP to initiate the process of a user verifying their address, or whether they were the 2nd/3rd/etc.  That creates an economic incentive for websites to use APs instead of trying to send a postcard themselves.

Hidden Attribute Provider
AP has no login system
AP might have a marketing page, but potentially 0 user-facing UI

IDP has a new URL where a user will be asked to enter self-asserted address
IDP has a new URL where a user can enter a code from a postcard

Simple AP exposes an API for SendPostCard (asserted name+address) - Done via a 2-legged OAuth2 request to identify the IDP.  The IDP and AP agree ahead of time about how the postcard looks, including the URL.  The AP creates a local entry in its list of mailrecipients and return a unique machine generated ID for that mailrecipient.  It also generates a code that it stores in the entry for that mailrecipient and prints on the postcard, and it saves the name of the IDP who made this request.

Simple AP exposes an API for VerifyPostCardCode(code, mailrecipient ID) - Done via a 2-legged OAth2 request to identify the IDP.  The AP checks if that code is a match, and if so updates the entry for that mailrecipient, and returns TRUE to the IDP, otherwise it returns FALSE.

Branded Attribute Provider
AP has an existing relationship with the user
AP has a login system
AP has a set of user interface pages to verify a user’s address, or they might have already verified it in the past

IDP has a new OAuth scope to WRITE StreetIdentity
API exposed is AddAddress (“display name”, mailrecipientID) - Done via a 3-legged OAuth2 request to identify the AttributeProvider.  Alternatively this might just be a redirect from the AP to the IDP with these variables as URLparameters if we decide that the security is reasonable.