UMA Legal: Relevant Functions and Flows
Below are two drafts describing UMA flows. These are both works in progress shared for informational context only.
The law can only be applied in a final way to actual facts, but can be notionally applied to hypothetical facts in postulated scenarios. The business/legal/technical integrated approach leveraged common types of technical descriptions to form legal fact patterns. Technical and business descriptions of such patterns as "user journey", "workflow" and "use case" and "functional model" can form the basis of a legal fact pattern with relatively little augmentation. Common technical descriptions focus on the relevant action, actor, sequence, input/output, state change or other functional and systemic aspects of a scenario. These are different terms and contexts but describe the same type of information needed for legal analysis of a situation, which will identify the responsible or affected parties, their conduct or other behavior, the digital or other assets and other material factors.
There is no more important aspect context than the "system" within which the use cases and other situations happen. This is sometimes technically referred to as the "security domain" or broader "network" and in business terms as the "company" or broader "extended enterprise" and in legal terms as the "corporation" or broader "jurisdiction". There is frequently more than one relevant system within which anything happens, depending on the level of abstraction and point of view. To elicit the general business, legal and technical boundaries encapsulating the most relevant systems within which something is happening, it is useful to identify "who owns, controls or is responsible for is in charge of the environment where this is happening". A quick technical method to establish the size and shape of boundaries surrounding a web-based operating environment is to identify what is inside and outside the "same origin policy". A quick legal method is to establish on whom one would serve notice of litigation if the operating environment caused a major crime, fraud or other loss.
Identifying the systems or environments where UMA is being used is essential to evaluate who is supposed to do what. The same activity happening in one environment may be eligible for no-fault reimbursement but have no remedy in another environment. Activity in one environment could constitute a crime and be perfectly legal in another environment. Sharing of the same personal data between the same parties may be required in one environment but prohibited in another. Establishing the business, legal and technical dimensions of the "system boundaries" where UMA is being used is important to correctly analyze the obligations and expectations all involved.
Boundaries between one system and another can be difficult to minutely and firmly establish, especially when fast changing multi-party dynamic systems are involved. A simpler and yet still valuable way to sufficiently identify the most important systems is to just identify the organizations or people involved, and the touchpoints (via interfaces) through which they are involved. This can provide a starting point to identify the input and output associated with the involved entities (both legal entities like consumers or businesses and technical entities like software and devices).
Looking to inputs and outputs of entities inside and between defined environments is a classic method of understanding systems of all types, from ecological to economic and beyond. An input expected from a registered OAuth 2 client is typically execution of a standard contract. By way of explanatory example, the ordinary "developer flow" involves legal assent to a "developer agreement" or equivalent contract prior to getting an authorization token. After assenting to the agreement but before receiving an authorization token, technical client registration information would ordinarily be collected (like a call-back URL) from which one could establish the network domains and other technical environments within which the client exists and externally interacts. Similarly, the legal entity who agreed to the developer contract would ordinarily provide the business name of the client software or service (like "Happy Productivity App") describing or associated with the service, software or other asset being accessed, created, exchanged, modified, etc. Based on the contextual information collected at time of client registration, one should necessarily be able to establish the legal entity responsible for that client by identifying "who signed the developer agreement". Identifying the signatory enables one to discover if the legal entity responsible for that technical entity is a major hospital chain, a city government agency or perhaps an individual entrepreneur with an asserted PO Box and email address. All of these legal entity identifiers are good enough in most cases to ensure the responsible party can be contacted and if potentially can be served legal notice. The ability to serve a party legal notice means that party potentially can be compelled to answer questions, address problems or even show up for litigation if necessary. Connected to the business and legal identity of this entity is the business and legal environment within which the entity operates. The business name of an app might identify software and be associated with a small team responsible for a single product of a larger company but the prevailing business environment may be quite different depending on the nature and reach of the company within which that product exists. So to, the broader business system might involve intermediary or augmenting environments like the iTunes market or a supply chain.
Both of the below flow descriptions provide rich sources of clues and context about the business, legal and technical factors that describe and predict how UMA may operate in practice. They are both technically oriented explanations but include or anticipate a number of basic business or legal factors are written in plain language suitable for a broad audience. We are fortunate to have two sources of such high quality and intelligent documentation from which legal fact patterns can be extrapolated. Again, these works are both in rough, early draft form and are provided solely as context and a starting point.
- By Eve Maler
- Draft Swimlane: UMA two-token approximation low-level with endpoints...
- Original: https://docs.google.com/document/d/1OsIqPbVNx66vypnCzjxoFjX0AHCD_rEmgP8Q-5hnFYQ/edit?usp=sharing
UMA issues 153-154 analysis and recommendation (from Eve)
Assuming issues 153 and 154 are resolved approximately as described in the accompanying swimlane...
The intended benefit of the change is to enable better alignment with OAuth, simplify UMA, and better enable implementations to account for multi-AS environments where an RqP might not ordinarily have had an account at an RO’s AS.
After WG discussion (APAC-friendly sync and 2015-08-06 telecon the next day), the following points have variously been raised.
1 Greater simplicity and alignment with OAuth is very attractive (weighing in favor of the original proposal).
2 Gathering RqP consent for claims flow is important (weighing against the original proposal; the accompanying swimlane guesses at a partial solution). Andi was first to speak on this.
3 Preserving the ability to perform step-up authentication and preserve other RqP context as part of trust elevation is important (weighing against the original proposal; a solution could potentially be worked out). see diagram from Domenico below.
In terms of absolute complexity for a developer working from scratch, the change is a modest reduction: from 7 endpoints total to 5 (or 6: some details are unclear), and from 3 tokens to 2. The new OAuth extension grant would still be fairly complex, involving at a minimum a client-to-RS-first flow, trust elevation round trips, permission tickets, and the like.
After working on the swimlane and thinking hard about the matter, I have the following observations, analysis, and recommendations.
Andi’s point about requiring RqP consent (authorization) resonates strongly, as this is fundamental to the reciprocity we have built into UMA from the beginning. While the model exists to serve Alice, on another day, it’s Bob’s turn to be in the RO’s seat. The model thus helps all parties become peers. I don’t think we’ve met this requirement in the change proposal yet, but I think it could be solved with more work, as could the trust elevation issues. Context preservation, obviously, requires a real cross-session relationship between the RqP and the AS.
Based on the customer and POC work I’m doing frequently these days, it seems clear that environments in which an RqP does have an account at the RO’s AS are not a tiny corner case, but will be a relatively common scenario in access federations, at least in the medium term; we have seen the same thing among identity federations for the last decade.
This is not to say we shouldn’t solve for the opposite case. As Justin notes in issue #154, “Supporting this would require the authorization server to either allow all external users to engage in OAuth transactions (unlikely) or to have a special-cased codepath for just the uma_authorization scope.” We differ in the assessment of likelihood, but it seems we do at least have a workaround available.
The notion of bringing a highly aligned solution to OAuth developers with an extension grant flow is appealing. However, after realizing that we don’t have all the design answers yet, time is running short (see the sprint themes and timeline here), the change is a breaking one, the impact to the spec is massive, and the extension grant flow is still a relatively heavy lift for a community of developers that is generally not even paying attention to UMA yet (versus those who are already strongly motivated by UMA use cases), I recommend that we keep the current “three-token”, “7-endpoint” design in V1.0 for V1.0.1, and take up issues 153 and 154 in a future major revision of UMA.
We can actually begin design work on it very soon if we wish, based on our recent agreement to treat our specs as if they were software and target different work streams for different versions. The usual mantra is to break things early, before many implementations are under way. However, with an agile model and modern version control, we essentially have the ability to signal and document what we intend to “break” far in advance, and even get feedback on it from the community we seek to attract.
- By Justin Richer, currently under discussion
- Consult the current Google Group email archive for emerging thread of discussion on this post.
- Original: https://groups.google.com/d/msg/kantara-initiative-uma-wg/a86oLezNggE/PDy7tkR7FAAJ
Since I wasn't able to make the call, let me try to lay it out end to end for people to see what I'm talking about:
-
Alice sets up a relationship between RS and AS, just like UMA says to do today. Done, no big deal.
-
Bob tells his client to access a resource, the resource says "no", and points bob's client at the AS along with a ticket (which should be passed in the response header, but that's another issue)
-
Bob's client registers with the AS (dynamically on its own, or by pestering bob to email an admin and do it the hard way, whatever).
-
Bob's client then sends a request to the token endpoint using a new OAuth grant type, let's call it grant_type=uma_authorization (in reality it's a URI but work with me here). The ticket is passed as another parameter, since it's just a simple string.
-
The combination of the client's own credentials and the ticket are sufficient to start the token request process for Bob's client.
-
As this is a call to the token endpoint, the client can even ask for a specific set of scopes, just like it could with a refresh token or other backchannel grant types.
-
The AS decides that it needs to know more about Bob before it can issue a token, so it responds with "need_info" to the client. Bob's client then figures out a way to get those claims to the AS, either by casting a spell and getting a magical assertion that can ignore audience restrictions and other security and sanity measures (which people have pointed out that they're already doing in practice) or by having Bob interactively present himself to the claims gathering endpoint.
-
If the client passes an assertion, it can do so to the token endpoint in a new parameter, like say uma_assertion=ejy...foo. Basically "oh let me try that again but with more stuff this time".
-
If the client sends Bob to the interactive claims gathering endpoint, Bob can log in to a local account, or use a federated login (like the OIDC model we used in PoF), or provide some shared secret that Alice emailed to him, or squint really, really hard at his screen -- whatever the claims require. The AS is still free to have this be whatever it wants, importantly including capturing Bob's consent to use the client (since it's identified itself here). [ Also note that in the alice-to-alice case, the AS can basically re-purpose its authorization endpoint after Alice logs in and this all collapses to vanilla OAuth. ]
-
With the claims probably in place, the client can try again at the token endpoint with the same ticket.
-
If the claims aren't good enough, repeat 6-9 ad nauseum until someone guesses the right set of claims (but that's another issue). If they're good enough, issue an OAuth token using the standard OAuth token endpoint response structure. This includes expiration, scopes, and other hints to the client. It can even include a refresh token, ID token, or other extension stuff. This also allows the RPT to be a PoP token without UMA having to say anything about whether or not it is, since token_type is a required response parameter and UMA can now inherit new token definitions.
Bob never sees or uses the authorization endpoint. Bob never needs an account (federated or othewise) at the AS that is capable of doing regular-user stuff like issuing OAuth tokens. The AS doesn't have to carve out special "external" accounts that only allow for the "uma_authorization" scope but not act as regular OAuth resource owners. (Remember, this is Alice's AS, not Bob's, and Bob has no business getting a regular OAuth token here.)
The AAT isn't needed for anything since Bob's client is identified directly and Bob is identified through claims (which already exist). The client could further be identified through claims if it wants to.
The RPT endpoint isn't needed since this is now just a slightly-specialized OAuth grant type. Many systems (including our own) already have hooks for extending with handlers for new grant types as this is once place where OAuth is already extensible. In our own implementation, we'd get handed the request from the token endpoint handler (which already validates the client and syntax of the input among other things)
The JSON response from the protected API isn't needed either since the ticket is a single string and can easily (and safely) be passed back in a header. ( again this is another issue but if we're breaking all wire compatibility let's get it right... and a note on the returning-the-ticket-as-a-header thing. It also opens the door for public API responses and discovery of multiple user stuff, like this (totally off the cuff):
Public data can be solved like: Bob's client talks to a URL with no token and gets back some data, but a header that says "if you want more go to this AS and present this ticket.
Multi-user data (like the userinfo endpoint) can be solved like: Bob's client talks to a URL and gets sent back a header that says "if you want more then give me an indicator of who you're after (an opaque token, a webfinger URI) or go to this interactive page to have Bob figure it out, then come back and we'll talk again". Basically, you can bootstrap the process with some user interaction that could lead into George's multi-stage protected discovery system. )
Someone is going to have to explain to me what is possible in the current system that is not possible in the above setup, because I'm not seeing anything.
Can we build it like it is today? Yes of course; I've done so myself. It works, but it's clunky and ugly and requires lots of special "if-uma-do-this" kind of code. I don't like that. It also requires Bob being able to do a regular OAuth flow to get the AAT even if he's not a local user, and I don't like that either.
So let's say we did things this way and called it UMA 2.0.0 (since this is a very backwards-incompatible change set and the group has adopted semantic versioning). What does that mean for me as a developer? Quite frankly, it means a whole lot less special code for implementing UMA at the AS, the client, and the RS, assuming I'm starting from an OAuth system. And it makes it much, much easier for me to have dual-purpose codebases that do both UMA and OAuth. Both of these are highly appealing to me as a systems architect and developer, and I don't think that I would be standing alone in this opinion.
-- Justin
On 8/6/2015 1:29 PM, Allan Foster wrote:
In the discussion there was talk of the new flow, and how we get Bob's consent.
It came to me that we are only talking about using the token endpoint, at the moment. In order to collect claims about Bob, wouldn't we need to use the User Endpoint?
If so, this should happen early in the flow, and is where the actual consent can be captured
Allan