< draft-richer-transactional-authz-01.txt   draft-richer-transactional-authz-02.txt >
Network Working Group J. Richer, Ed. Network Working Group J. Richer, Ed.
Internet-Draft Bespoke Engineering Internet-Draft Bespoke Engineering
Intended status: Standards Track July 3, 2019 Intended status: Standards Track July 8, 2019
Expires: January 4, 2020 Expires: January 9, 2020
Transactional Authorization Transactional Authorization
draft-richer-transactional-authz-01 draft-richer-transactional-authz-02
Abstract Abstract
This document defines a mechanism for delegating authorization to a This document defines a mechanism for delegating authorization to a
piece of software, and conveying that delegation to the software. piece of software, and conveying that delegation to the software.
Requirements Language Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
skipping to change at page 1, line 39 skipping to change at page 1, line 39
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 4, 2020. This Internet-Draft will expire on January 9, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 20 skipping to change at page 2, line 20
Table of Contents Table of Contents
1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Sequence . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Sequence . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Transaction request . . . . . . . . . . . . . . . . . . . . . 3 2. Transaction request . . . . . . . . . . . . . . . . . . . . . 3
2.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Resource . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Resource . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3. User . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. User . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4. Interact . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Interact . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3. Interaction response . . . . . . . . . . . . . . . . . . . . 7 3. Interaction response . . . . . . . . . . . . . . . . . . . . 7
3.1. Redirect interaction . . . . . . . . . . . . . . . . . . 8 3.1. Redirect interaction . . . . . . . . . . . . . . . . . . 8
3.2. Callback response . . . . . . . . . . . . . . . . . . . . 9 3.2. Callback response . . . . . . . . . . . . . . . . . . . . 9
3.3. Secondary device interaction . . . . . . . . . . . . . . 9 3.3. Secondary device interaction . . . . . . . . . . . . . . 9
4. Wait response . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Wait response . . . . . . . . . . . . . . . . . . . . . . . . 10
5. Interaction at the AS . . . . . . . . . . . . . . . . . . . . 11 5. Interaction at the AS . . . . . . . . . . . . . . . . . . . . 11
6. Error response . . . . . . . . . . . . . . . . . . . . . . . 11 6. Error response . . . . . . . . . . . . . . . . . . . . . . . 12
7. Transaction continue request . . . . . . . . . . . . . . . . 12 7. Transaction continue request . . . . . . . . . . . . . . . . 12
8. Token response . . . . . . . . . . . . . . . . . . . . . . . 13 8. Token response . . . . . . . . . . . . . . . . . . . . . . . 13
8.1. Presenting Tokens to the RS . . . . . . . . . . . . . . . 13 8.1. Presenting Tokens to the RS . . . . . . . . . . . . . . . 13
9. Handle references . . . . . . . . . . . . . . . . . . . . . . 13 9. Handle references . . . . . . . . . . . . . . . . . . . . . . 13
9.1. Presenting handles . . . . . . . . . . . . . . . . . . . 14 9.1. Presenting handles . . . . . . . . . . . . . . . . . . . 14
9.2. Validating handles . . . . . . . . . . . . . . . . . . . 14 9.2. Validating handles . . . . . . . . . . . . . . . . . . . 14
9.3. Transaction handles . . . . . . . . . . . . . . . . . . . 14 9.3. Transaction handles . . . . . . . . . . . . . . . . . . . 14
9.4. Client handles . . . . . . . . . . . . . . . . . . . . . 15 9.4. Client handles . . . . . . . . . . . . . . . . . . . . . 15
9.5. Resource handles . . . . . . . . . . . . . . . . . . . . 15 9.5. Resource handles . . . . . . . . . . . . . . . . . . . . 15
9.5.1. Resource-first . . . . . . . . . . . . . . . . . . . 16 9.5.1. Resource-first . . . . . . . . . . . . . . . . . . . 16
9.6. User handles . . . . . . . . . . . . . . . . . . . . . . 17 9.6. User handles . . . . . . . . . . . . . . . . . . . . . . 17
9.7. Key handles . . . . . . . . . . . . . . . . . . . . . . . 17 9.7. Key handles . . . . . . . . . . . . . . . . . . . . . . . 17
10. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 18 10. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 18
10.1. Binding a key to a transaction . . . . . . . . . . . . . 18 10.1. Binding a key to a transaction . . . . . . . . . . . . . 18
10.2. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 19 10.2. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 19
10.3. Validating MTLS . . . . . . . . . . . . . . . . . . . . 19 10.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 19
10.4. Validating DID . . . . . . . . . . . . . . . . . . . . . 19 10.4. Validating DID . . . . . . . . . . . . . . . . . . . . . 19
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
13. Security Considerations . . . . . . . . . . . . . . . . . . . 19 13. Security Considerations . . . . . . . . . . . . . . . . . . . 19
14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20
15. Normative References . . . . . . . . . . . . . . . . . . . . 20 15. Normative References . . . . . . . . . . . . . . . . . . . . 20
Appendix A. Document History . . . . . . . . . . . . . . . . . . 21 Appendix A. Document History . . . . . . . . . . . . . . . . . . 21
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21
1. Protocol 1. Protocol
This protocol allows a piece of software to request delegated This protocol allows a piece of software to request delegated
authorization to an API, protected by an authorization server usually authorization to an API, protected by an authorization server usually
on behalf of a resource owner. on behalf of a resource owner.
1.1. Parties 1.1. Parties
The Authorization Server (AS) manages the transactions. It is The Authorization Server (AS) manages the transactions. It is
defined by its transaction endpoint, a single URL that accepts a POST defined by its transaction endpoint, a single URL that accepts a POST
request with a JSON payload. The AS MAY also have other endpoints, request with a JSON payload. The AS MAY also have other endpoints,
including interaction endpoints, but these are including interaction endpoints and user code endpoints, and these
are introduced to the RC as needed during the transaction process.
The Resource Client (RC) requests tokens from the AS and uses tokens The Resource Client (RC) requests tokens from the AS and uses tokens
at the RS. at the RS.
The Resource Server (RS) accepts tokens from the RC and validates The Resource Server (RS) accepts tokens from the RC and validates
them (potentially at the AS). them (potentially at the AS).
The Resource Owner (RO) authorizes the request from the RC to the RS, The Resource Owner (RO) authorizes the request from the RC to the RS,
often interactively at the AS. often interactively at the AS.
skipping to change at page 3, line 39 skipping to change at page 3, line 40
1. The RC creates a transaction request and sends it to the AS 1. The RC creates a transaction request and sends it to the AS
2. The AS processes the transaction request and determines if the RO 2. The AS processes the transaction request and determines if the RO
needs to interact needs to interact
3. If interaction is required, the AS interacts with the RO, 3. If interaction is required, the AS interacts with the RO,
possibly by directing the RC to send the RO there possibly by directing the RC to send the RO there
4. The RC continues the transaction at the AS 4. The RC continues the transaction at the AS
5. The AS processess the transaction again, determining that a token 5. The AS processes the transaction again, determining that a token
can be issued can be issued
6. The AS issues a token to the RC 6. The AS issues a token to the RC
7. The RC uses the token with the RS 7. The RC uses the token with the RS
2. Transaction request 2. Transaction request
To start a transaction, the RC makes a transaction request to the To start a transaction, the RC makes a transaction request to the
transaction endpoint of the AS. The RC creates a JSON [RFC8259] transaction endpoint of the AS. The RC creates a JSON [RFC8259]
skipping to change at page 5, line 44 skipping to change at page 5, line 44
data: ["foo", "bar"] data: ["foo", "bar"]
} }
] ]
This can also be presented as a set of resource handle references This can also be presented as a set of resource handle references
Section 9.5, or a combination of handles and resource structures. Section 9.5, or a combination of handles and resource structures.
2.3. User 2.3. User
This section provides a verifiable assertion about the RO interacting This section provides a verifiable assertion about the person
with the RC on behalf of the request. interacting with the RC on behalf of the request. This person MAY be
the RO or MAY be another party.
assertion The value of the assertion as a string. assertion The value of the assertion as a string.
type The type of the assertion. Possible values include type The type of the assertion. Possible values include
"oidc_id_token"... "oidc_id_token"...
user: { user: {
assertion: "eyj0....", assertion: "eyj0....",
type: "oidc_id_token" type: "oidc_id_token"
} }
This can also be presented as a user handle reference Section 9.6. This can also be presented as a user handle reference Section 9.6.
2.4. Interact 2.4. Interact
This section provides details of how the RC can interact with the RO. This section provides details of how the RC can interact with the RO.
All interact requests MUST have the "type" field. All interact requests MUST have the "type" field.
type REQUIRED. Type of interaction. Can be "redirect" or "device". type REQUIRED. Type of interaction. MAY be "redirect" or "device".
The "redirect" type indicates that the RO is capable of sending The "redirect" type indicates that the RO is capable of sending
the user to an arbitrary URL to be returned from the AS. The the user to an arbitrary URL to be returned from the AS. The
"device" type indicates that the RC is capable of communicating a "device" type indicates that the RC is capable of communicating a
short, human-readable code to the RO, which the RO can enter short, human-readable code to the RO, which the RO can enter
interactively to the AS. interactively to the AS.
callback OPTIONAL. IF the RC is capable of receiving inbound callback OPTIONAL. IF the RC is capable of receiving inbound
messages from the RO's browser, this indicates the URI to send the messages from the RO's browser, this indicates the URI to send the
RO to after interaction. This URI SHOULD (MUST?) be unique per RO to after interaction. This URI SHOULD (MUST?) be unique per
transaction and MUST be hosted or accessible by the RC. This URI transaction and MUST be hosted or accessible by the RC. This URI
skipping to change at page 6, line 45 skipping to change at page 6, line 45
state REQUIRED if the "callback" parameter is used. Unique value to state REQUIRED if the "callback" parameter is used. Unique value to
be returned to the application as a query parameter on the be returned to the application as a query parameter on the
callback URL, must be sufficiently random to be unguessable by an callback URL, must be sufficiently random to be unguessable by an
attacker. MUST be generated by the RC for this transaction. attacker. MUST be generated by the RC for this transaction.
Each interaction type has its own parameters and behaviors, detailed Each interaction type has its own parameters and behaviors, detailed
below. below.
This section MUST NOT be represented by a handle reference. (Note: This section MUST NOT be represented by a handle reference. (Note:
this this decision is largely due to the "state" and "callback" being
variable per transaction. We could allow a handle but restrict it to
device-only -- but in that case, it's simpler and shorter to just
send the device type.)
2.5. Keys 2.5. Keys
This section lists the keys that the RC can present proof of This section lists the keys that the RC can present proof of
ownership. The RC MUST send at least one key. The RC MAY send more ownership. The RC MUST send at least one key. The RC MAY send more
than one key, but only one key of each type. than one key, but only one key of each type. (Note: Do we want to
have multiple keys of various types instead?)
jwks Value of the public key as a JWK Set JSON object [Note: should jwks Value of the public key as a JWK Set JSON object [Note: should
this be a single JWK instead? And do we want to bother with url- this be a single JWK instead? And do we want to bother with url-
based references?]. MUST contain an "alg" field which is used to based references?]. MUST contain an "alg" field which is used to
validate the signature. MUST contain the "kid" field to identify validate the signature. MUST contain the "kid" field to identify
the key in the signed object. This key type MUST be proved using the key in the signed object. This key type MUST be proved using
either the detached JWS or HTTP-Signing mechanisms. either the detached JWS or HTTP-Signing mechanisms.
cert String serialized value of the certificate thumbprint as per cert String serialized value of the certificate thumbprint as per
OAuth-MTLS. This key type MUST be proved using Mutual TLS. OAuth-MTLS. This key type MUST be proved using Mutual TLS.
skipping to change at page 7, line 49 skipping to change at page 8, line 9
needs to have the RO present to interact with the AS before issuing a needs to have the RO present to interact with the AS before issuing a
token. This interaction can include the RO logging in to the AS, token. This interaction can include the RO logging in to the AS,
authorizing the transaction, providing proof claims, determining if authorizing the transaction, providing proof claims, determining if
the transaction decision should be remembered for the future, and the transaction decision should be remembered for the future, and
other items. other items.
The AS responds to the RC based on the type of interaction supported The AS responds to the RC based on the type of interaction supported
by the RC in the transaction request. by the RC in the transaction request.
This response can indicate a set of keys are bound to the transaction This response can indicate a set of keys are bound to the transaction
as in Key Binding. This response includes a transaction handle as in as in Key Binding. This response includes a transaction handle as
Transaction Handle. described in Section 9.3.
3.1. Redirect interaction 3.1. Redirect interaction
If the RC supports a "redirect" style interaction, the AS creates a If the RC supports a "redirect" style interaction, the AS creates a
unique interaction URL and returns it to the RC. This URL MUST be unique interaction URL and returns it to the RC. This URL MUST be
associated with a single pending transaction. associated with a single pending transaction.
interaction_url The interaction URL that the RC will direct the RO interaction_url The interaction URL that the RC will direct the RO
to. This URL MUST be unique to this transaction request. The URL to. This URL MUST be unique to this transaction request. The URL
SHOULD contain a random portion of sufficient entropy so as not to SHOULD contain a random portion of sufficient entropy so as not to
skipping to change at page 13, line 34 skipping to change at page 13, line 41
value: "tghji76ytghj9876tghjko987yh", value: "tghji76ytghj9876tghjko987yh",
type: "bearer" type: "bearer"
} }
} }
8.1. Presenting Tokens to the RS 8.1. Presenting Tokens to the RS
A bearer style access token MUST be presented using the Header method A bearer style access token MUST be presented using the Header method
of OAuth 2 Bearer Tokens [RFC6750]. A sha3 style access token is of OAuth 2 Bearer Tokens [RFC6750]. A sha3 style access token is
hashed as described in Section 9 and presented using the Header hashed as described in Section 9.1 and presented using the Header
method of OAuth 2 Bearer Tokens [RFC6750]. method of OAuth 2 Bearer Tokens [RFC6750].
An access token MAY be bound to any keys presented by the client An access token MAY be bound to any keys presented by the client
during the transaction request. A bound access token MUST be during the transaction request. A bound access token MUST be
presented with proof of the key as described in Section 10. presented with proof of the key as described in Section 10.
9. Handle references 9. Handle references
A handle in this protocol is a value presented from one party to A handle in this protocol is a value presented from one party to
another as proof that they are the appropriate party for part of the another as proof that they are the appropriate party for part of the
skipping to change at page 15, line 51 skipping to change at page 16, line 6
} }
9.5. Resource handles 9.5. Resource handles
Resource handles stand in for the detailed resource request in the Resource handles stand in for the detailed resource request in the
transaction requestSection 2.2. Resource handles MAY be created by transaction requestSection 2.2. Resource handles MAY be created by
the authorization server as static stand-ins for specific resource the authorization server as static stand-ins for specific resource
requests, analogous to OAuth2 scopes. requests, analogous to OAuth2 scopes.
Resource handles MAY be issued by the RS in response to a transaction Resource handles MAY be issued by the RS in response to a transaction
request. When the RC receives this handle, it MAY present the handle request. In such cases, the resource handle returned represents the
in future transaction requests instead of sending its information total of all resources
again.
{ {
handle: { handle: {
value: "tghji76ytghj9876tghjko987yh", value: "tghji76ytghj9876tghjko987yh",
method: "bearer" method: "bearer"
}, },
resource_handle: { resource_handle: {
value: "foo", value: "foo",
method: "bearer" method: "bearer"
skipping to change at page 16, line 29 skipping to change at page 16, line 31
The RC sends its handle in lieu of the resource block of the future The RC sends its handle in lieu of the resource block of the future
transaction request: transaction request:
{ {
resources: ["foo"] resources: ["foo"]
} }
Handles and object values MAY be combined. Handles and object values MAY be combined in a single request.
{ {
resources: [ resources: [
"foo", "foo",
{ {
actions: ["read", "write"], actions: ["read", "write"],
locations: ["https://exapmle.com/resource"] locations: ["https://exapmle.com/resource"]
data: ["foo", "bar"] data: ["foo", "bar"]
} }
skipping to change at page 19, line 23 skipping to change at page 19, line 23
The RC presents the signature in the JWS-Signature HTTP Header field. The RC presents the signature in the JWS-Signature HTTP Header field.
[Note: this is a custom header field, do we need this?] [Note: this is a custom header field, do we need this?]
JWS-Signature: eyj0.... JWS-Signature: eyj0....
When the AS receives the JWS-Signature header, it MUST parse its When the AS receives the JWS-Signature header, it MUST parse its
contents as a detached JWS object. The HTTP Body is used as the contents as a detached JWS object. The HTTP Body is used as the
payload for purposes of validating the JWS, with no transformations. payload for purposes of validating the JWS, with no transformations.
10.3. Validating MTLS 10.3. Mutual TLS
The RC presents its client certificate during TLS negotiation with The RC presents its client certificate during TLS negotiation with
the server (either AS or RS). The AS or RS takes the thumbprint of the server (either AS or RS). The AS or RS takes the thumbprint of
the client certificate presented during mutual TLS negotiation and the client certificate presented during mutual TLS negotiation and
compares that thumbprint to the thumbprint presented by the RC compares that thumbprint to the thumbprint presented by the RC
application. application.
10.4. Validating DID 10.4. Validating DID
[[ Note: validation of DID-based keys could potentially be either [[ Note: validation of DID-based keys could potentially be either
skipping to change at page 19, line 50 skipping to change at page 19, line 50
11. Acknowledgements 11. Acknowledgements
12. IANA Considerations 12. IANA Considerations
This specification creates one registry and registers several values This specification creates one registry and registers several values
into existing registries. into existing registries.
13. Security Considerations 13. Security Considerations
All requests have to be over TLS or equivalent. All requests have to be over TLS or equivalent. Many handles act as
shared secrets, though they can be combined with a requirement to
provide proof of a key as well.
14. Privacy Considerations 14. Privacy Considerations
Handles are passed between parties and therefore should be stateful Handles are passed between parties and therefore should be stateful
and not contain any internal structure or information, which could and not contain any internal structure or information, which could
leak private data. leak private data.
15. Normative References 15. Normative References
[BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre,
skipping to change at page 21, line 12 skipping to change at page 21, line 12
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
Appendix A. Document History Appendix A. Document History
- 02
o Minor editorial cleanups.
- 01 - 01
o Made JSON multimodal for handle requests. o Made JSON multimodal for handle requests.
o Major updates to normative language and references throughout o Major updates to normative language and references throughout
document. document.
o Allowed interaction to split between how the user gets to the AS o Allowed interaction to split between how the user gets to the AS
and how the user gets back. and how the user gets back.
 End of changes. 19 change blocks. 
23 lines changed or deleted 34 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/