Draft: draft-ietf-gnap-core-protocol

Commentary: This change set updates a number of security - related discussions and inserts forward - links to the security considerations section . add security consideration anchors and MTLS discussions , add forward links for bearer token considerations from relevant portions , - add forward references for impersonation and symmetric keys , - considerations for phishing attacks , - updated HTTPSig examples , 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Section 7.3 states that all key binding methods must cover the HTTP method being used . In the example in section 7.3.1 , this seems to be accomplished by the component identifier . Its value there is . According to the , however , this component identifier should not contain the HTTP method at all . Rather , the component identifier should be used in addition . Am I missing something here ? 
 There were changes to the HTTP Message Signatures draft in a recent revision that redefined how worked . It used to include the ( lowercased ) method and " request line " portion , which was all kinds of broken for proper HTTP usage . The examples and details in this section need to be updated to use the new and identifiers instead . 
 Both and in the access request will be used by the AS and the RO to make security - related decisions . But they are completely determined by the  , and are not bound in any way to the client 's identity ( i.e. , its key ) . I suggest to add this text : Note : this is related to but not exactly the same . 
 The above is stronger than the current language : 
 I think we should go so far as to say pre - registered values MUST NOT be overridden ( or to ) by any runtime - presented values , as well . 
 Addressed in security considerations : Will add text in 2.3 ( and possibly 2.3.2 ) to add normative requirement for not overriding at runtime 
 Bearer tokens are so easy to be forwarded by a client to another client that they should not be supported . This does not mean that one client can not forward sender - constrained tokens to another client , but this is less straightforward . 
 The attacks on bearer tokens do n't involve a client knowingly forwarding the token , but rather another party such as the rs using or forwarding the token . A client can always simply forward the key material , or even make a call on behalf of someone else . Nothing can stop that . This was discussed extensively when the group was founded . There is strong desire to keep support for bearer tokens but GNAP has made them non - default and requires them to be flagged specially . 
 Agreed , a client can voluntarily share key material and tokens or even raw data , and there 's no way to stop that . Like Justin said , the interesting things that can be prevented by avoiding bearer tokens are parties other than the client ( e.g. a Resource Server ) passing on the token accidentally or maliciously . That said , there are still cases where this is not a concern , such as when all roles ( client , RS , AS ) are controlled by a single entity , in which case the simplicity of bearer tokens may be appealing . 
 wrote : This forwarding attack by a RS can easily be countered . It is sufficient to include into the access token either a true identifier or a concealed identifier of the RS , so that each RS can verify to which RS the access token was intended to . This has been explained on the mailing list about one year ago . This is an additional argument why the structure of the access token should be defined in the core document . also wrote : Indeed , it is possible that a user forwards the key material to another , but the attack is less easy for the second user if the token is a sender - constrained token . However , the sentence " Nothing can stop that " is inappropriate . Collusion attacks between two users can not be prevented but can be detected . If the RS is capable to perform that detection , then the attack can be defeated ( and thus " stopped " ) . If a client simply makes a call on behalf of someone else , it will be get attributes and/or rights associated with that someone else . It may impersonate that someone else but this does not mean that the attributes and rights from someone can be mixed with the attributes and rights from that someone else . Details on how to defeat user collaborative attacks and their implications are discussed in issue . 
 please respond to my comment on before continuing to repeat arguments in other issues 
 I have just replied to your comment on 
 Bearer tokens are not recommended according to the security considerations in 
 We rightly avoid normative language in the Security Considerations . But should we add to the description of the flag in 3.2.1 , 
 We might , although I think it 's too strong . Bearer tokens might be reasonable in a number of cases . 
 Under certain circumstances , GNAP could be used to create phishing links at the authorization server 's domain . This should be listed as a security consideration , along with the circumstances under which this can happen and how to avoid it . Specifically , if a malicious developer uses a public GNAP API ( e.g.  , google , twitter ) with a redirect URI of the attacker 's website , the attacker could initiate a GNAP flow to get an interact redirect from the server , then send the resulting URL to the victim . The URL would appear legitimate since it would be the authorization server 's domain , but then would redirect to the attacker 's website . The redirect may either be successful or an error case , but both would have caused the victim to be sent to the attacker 's website in either case . There is no mitigation for this situation , so it should be called out so developers are aware of the risk . To avoid the potential for these attacks , the authorization server would need to prevent arbitrary clients from initiating flows by requiring authentication of the initial client request . 
  authorization is one mitigation , and an allowlist / blocklist / warning of the target URL is another . This can even be enforced , at least partially , on initial request since the URL is n't passed in the front channel . 
 Related ( but with different trust metrics ): the AS can send an arbitrary URL back to the client , which the client will launch the user to . 
 Mutual TLS : Editor 's note : This method requires no changes to the HTTP message itself , since the security relies on the TLS layer . However , the application level will need to validate that the certificate key used in the request is the one expected for the specific request . 
 most systems that i work on do not expose the ssl key to the application layer . I find the whole idea of mixing layers ( aka channel binding ) to be problematic from a security perspective . I similarly was happy to see token binding go away and expect the same will happen here . 
 This needs to be addressed specifically in the security considerations , and probably forward - referenced from the MTLS section .
Paragraph (version A):
This specification focuses on the portions of the delegation process
facing the client instance.  In particular, this specification
defines interoperable methods for a client instance to request,
negotiate, and receive access to information facilitated by the
authorization server.  This specification also discusses discovery
mechanisms for the client instance to configure itself dynamically.
The means for an authorization server and resource server to
interoperate are discussed in the companion document, I-D.draft-ietf-
gnap-resource-servers.
Paragraph (version B):
This specification focuses on the portions of the delegation process
facing the client instance.  In particular, this specification
defines interoperable methods for a client instance to request,
negotiate, and receive access to information facilitated by the
authorization server.  This specification also discusses discovery
mechanisms for the client instance to configure itself dynamically.
The means for an authorization server and resource server to
interoperate are discussed in the companion document, I-D.ietf-gnap-
resource-servers.
Paragraph (version A):
AS/RS: the AS promises to issue valid access tokens to legitimate
client requests (i.e. after carrying out appropriate due
diligence, as defined in the GNAP protocol).  Some optional
configurations are covered by I-D.draft-ietf-gnap-resource-
servers.
Paragraph (version B):
AS/RS: the AS promises to issue valid access tokens to legitimate
client requests (i.e. after carrying out appropriate due
diligence, as defined in the GNAP protocol).  Some optional
configurations are covered by I-D.ietf-gnap-resource-servers.
Paragraph (version B):
If this flag is included, the access token being requested is a
bearer token.  If this flag is omitted, the access token is bound
to the key used by the client instance in this request (or that
key's most recent rotation) and the access token MUST be presented
using the same key and proofing method.  Methods for presenting
bound and bearer access tokens are described in use-access-token.
See security-bearer-tokens for additional considerations on the
use of bearer tokens.
Paragraph (version A):
Note: the "formats" and "assertions" request fields are independent
of each other, and a returned assertion MAY omit a requested subject
identifier.
Paragraph (version B):
Note: the "formats" and "assertions" request fields are independent
of each other, and a returned assertion MAY use a different subject
identifier.
Paragraph (version A):
Note that the AS MAY know the client instance's public key ahead of
time, and the AS MAY apply different policies to the request
depending on what has been registered against that key.  If the same
public key is sent by value on subsequent access requests, the AS
SHOULD treat these requests as coming from the same client instance
for purposes of identification, authentication, and policy
application.  If the AS does not know the client instance's public
key ahead of time, the AS MAY accept or reject the request based on
AS policy, attestations within the "client" request, and other
mechanisms.
Paragraph (version B):
If the same public key is sent by value on different access requests,
the AS MUST treat these requests as coming from the same client
instance for purposes of identification, authentication, and policy
application.  If the AS does not know the client instance's public
key ahead of time, the AS MAY accept or reject the request based on
AS policy, attestations within the "client" request, and other
mechanisms.
Paragraph (version B):
The client instance MUST NOT send a symmetric key by value in the
request, as doing so would expose the key directly instead of simply
proving possession of it.  See considerations on symmetric keys in
security-symmetric.
Paragraph (version B):
The client instance's key MAY be pre-registered with the AS ahead of
time and associated with a set of policies and allowable actions
pertaining to that client.  If this pre-registration includes other
fields that can occur in the "client" request object described in
this section, such as "class_id" or "display", the pre-registered
values MUST take precedence over any values given at runtime.
Additional fields sent during a request but not present in a pre-
registered client instance record at the AS SHOULD NOT be added to
the client's pre-registered record.  See additional considerations
regarding client instance impersonation in security-impersonation.
Paragraph (version A):
If the client instance is identified in this manner, the registered
key for the client instance MAY be a symmetric key known to the AS.
The client instance MUST NOT send a symmetric key by value in the
request, as doing so would expose the key directly instead of proving
possession of it.
Paragraph (version B):
If the client instance is identified in this manner, the registered
key for the client instance MAY be a symmetric key known to the AS.
See considerations on symmetric keys in security-symmetric.
Paragraph (version A):
The AS SHOULD use these values during interaction with the RO.  The
values are for informational purposes only and MUST NOT be taken as
authentic proof of the client instance's identity or source.  The AS
MAY restrict display values to specific client instances, as
identified by their keys in request-client.
Paragraph (version B):
The AS SHOULD use these values during interaction with the RO.  The
values are for informational purposes only and MUST NOT be taken as
authentic proof of the client instance's identity or source.  The AS
MAY restrict display values to specific client instances, as
identified by their keys in request-client.  See additional
considerations for displayed client information in security-
impersonation.
Paragraph (version A):
This flag indicates whether the token is bound to the client
instance's key.  If the "bearer" flag is present, the access token
is a bearer token, and the "key" field in this response MUST be
omitted.  If the "bearer" flag is omitted and the "key" field in
this response is omitted, the token is bound the request-client in
its request for access.  If the "bearer" flag is omitted, and the
"key" field is present, the token is bound to the key and proofing
mechanism indicated in the "key" field.
Paragraph (version B):
This flag indicates whether the token is a bearer token, not bound
to a key and proofing mechanism.  If the "bearer" flag is present,
the access token is a bearer token, and the "key" field in this
response MUST be omitted.  If the "bearer" flag is omitted and the
"key" field in this response is omitted, the token is bound the
request-client in its request for access.  If the "bearer" flag is
omitted, and the "key" field is present, the token is bound to the
key and proofing mechanism indicated in the "key" field.  See
security-bearer-tokens for additional considerations on the use of
bearer tokens.
Paragraph (version B):
See security-polling for considerations on polling for continuation
without an interaction "finish" method.
Paragraph (version A):
The key binding methods in this section MAY be used by other
components making calls as part of GNAP, such as the extensions
allowing the RS to make calls to the AS defined in {{I-D.ietf-gnap-
resource-servers}}. To facilitate this extended use, the sections
below are defined in generic terms of the "signer" and "verifier" of
the HTTP message.  In the core functions of GNAP, the "signer" is the
client instance and the "verifier" is the AS or RS, as appropriate.
Paragraph (version B):
The key binding methods in this section MAY be used by other
components making calls as part of GNAP, such as the extensions
allowing the RS to make calls to the AS defined in I-D.ietf-gnap-
resource-servers.  To facilitate this extended use, the sections
below are defined in generic terms of the "signer" and "verifier" of
the HTTP message.  In the core functions of GNAP, the "signer" is the
client instance and the "verifier" is the AS or RS, as appropriate.
Paragraph (version A):
The Digest header as defined in RFC3230.  When the request message
has a body, the signer MUST calculate this header value and the
verifier MUST validate this header.
Paragraph (version B):
The Content-Digest or Digest header as defined in I-D.ietf-
httpbis-digest-headers.  When the request message has a body, the
signer MUST calculate this header value and the verifier MUST
validate this field value.  Use of Content-Digest is RECOMMENDED.
Use of content-encoding agnostic digest methods (such as "id-sha-
256") is RECOMMENDED.
Paragraph (version A):
Other covered content MAY also be included.
Paragraph (version B):
Other message components MAY also be included.
Paragraph (version A):
If the HTTP Message includes a message body, the verifier MUST
calculate and verify the value of the "Digest" header.  The verifier
MUST ensure that the signature includes all required covered content.
The verifier MUST validate the signature against the expected key of
the signer.
Paragraph (version B):
If the HTTP Message includes a message body, the verifier MUST
calculate and verify the value of the "Digest" or "Content-Digest"
header.  The verifier MUST ensure that the signature covers all
required message components.  The verifier MUST validate the
signature against the expected key of the signer.
Paragraph (version A):
Note that in many instances, the verifier will not do a full
certificate chain validation of the presented TLS client certificate,
as the means of trust for this certificate could be in something
other than a PKI system, such as a static registration or trust-on-
first-use.
Paragraph (version B):
Note that in many instances, the verifier will not do a full
certificate chain validation of the presented TLS client certificate,
as the means of trust for this certificate could be in something
other than a PKI system, such as a static registration or trust-on-
first-use.  See security-mtls and security-mtls-patterns for some
additional considerations for this key proofing method.
Paragraph (version A):
dynamic methods are discussed in I-D.draft-ietf-gnap-resource-
servers.  The content of the resource reference is opaque to the
client instance.
Paragraph (version B):
dynamic methods are discussed in I-D.ietf-gnap-resource-servers.  The
content of the resource reference is opaque to the client instance.
Paragraph (version A):
All requests in GNAP have to be made over TLS or equivalent as
outlined in BCP195 to protect the contents of the request and
response from manipulation and interception by an attacker.  This
includes all requests from a client instance to the AS, all requests
from the client instance to an RS, any requests back to a client
instance such as the push-based interaction finish method, and any
back-end communications such as from an RS to an AS as described in
I-D.draft-ietf-gnap-resource-servers.  Additionally, all requests
between a browser and other components, such as during redirect-based
interaction, need to be made over TLS or use equivalent protection.
Paragraph (version B):
All requests in GNAP have to be made over TLS or equivalent as
outlined in BCP195 to protect the contents of the request and
response from manipulation and interception by an attacker.  This
includes all requests from a client instance to the AS, all requests
from the client instance to an RS, any requests back to a client
instance such as the push-based interaction finish method, and any
back-end communications such as from an RS to an AS as described in
I-D.ietf-gnap-resource-servers.  Additionally, all requests between a
browser and other components, such as during redirect-based
interaction, need to be made over TLS or use equivalent protection.
Paragraph (version A):
GNAP does not specify how a client instance's keys could be made
known to the AS ahead of time.  Public Key Infrastructure (PKI) can
be used to manage the keys used by client instances when calling the
AS, allowing the AS to trust a root key from a trusted authority.
This method is particularly relevant to the MTLS signature method,
Paragraph (version B):
The mtls provides a means for a client instance to present a key
using a certificate the TLS layer.  Since TLS protects the entire
HTTP message in transit, verification of the TLS client certificate
presented with the message provides a sufficient binding between the
two.  However, since TLS is functioning at a separate layer from
HTTP, there is no direct connection between the TLS key presentation
and the message itself, other than the fact that the message was
presented over the TLS channel.  That is to say, any HTTP message can
be presented over the TLS channel in question with the same level of
trust.  The verifier is responsible for ensuring the key in the TLS
client certificate is the one expected for a particular request.  For
example, if the request is a grant request [42], the AS needs to
compare the TLS client certificate presented at the TLS layer to the
key identified in the request body itself (either by value or through
a referenced identifier).
Paragraph (version B):
Furthermore, the prevalence of the TLS-terminating reverse proxy
(TTRP) pattern in deployments adds a wrinkle to the situation.  In
this common pattern, the TTRP validates the TLS connection and then
forwards the HTTP message contents onward to an internal system for
processing.  The system processing the HTTP message no longer has
access to the original TLS connection's information and context.  To
compensate for this, the TTRP could inject the TLS client certificate
into the forwarded request as a header parameter using I-D.ietf-
httpbis-client-cert-field, giving the downstream system access to the
certificate information.  The TTRP has to be trusted to provide
accurate certificate information, and the connection between the TTRP
and the downstream system also has to be protected.  The TTRP could
provide some additional assurance, for example, by adding its own
signature to the "Client-Cert" header field using I-D.ietf-httpbis-
message-signatures.  This signature would be effectively ignored by
GNAP but understood by the downstream service as part of its
deployment.
Paragraph (version B):
Additional considerations for different types of deployment patterns
and key distribution mechanisms for MTLS are found in security-mtls-
patterns.
Paragraph (version B):
GNAP does not specify how a client instance's keys could be made
known to the AS ahead of time.  Public Key Infrastructure (PKI) can
be used to manage the keys used by client instances when calling the
AS, allowing the AS to trust a root key from a trusted authority.
This method is particularly relevant to the MTLS key proofing method,
Paragraph (version A):
MTLS need not use a PKI backing, as self-signed certificates and
certificates from untrusted authorities can still be presented as
part of a TLS connection.  In this case, the AS or RS would validate
the connection but accept whatever certificate was presented by the
client software.  This specific certificate would then be bound to
all future connections from that client software by being bound to
the resulting access tokens.
Paragraph (version B):
MTLS in GNAP need not use a PKI backing, as self-signed certificates
and certificates from untrusted authorities can still be presented as
part of a TLS connection.  In this case, the verifier would validate
the connection but accept whatever certificate was presented by the
client software.  This specific certificate would then be bound to
all future connections from that client software by being bound to
the resulting access tokens.  See security-mtls for more
considerations on MTLS as a key proofing mechanism.
Paragraph (version B):
Some interaction methods in GNAP make use of URLs accessed through
the end-user's browser, known collectively as front-channel
communication.  These URLs are most notably present in the "redirect"
interaction "start" method and the "redirect" interaction "finish"
mode.  Since these URLs are intended to be given to the end-user, the
end user and their browser will be subjected to anything hosted at
that URL including viruses, malware, and phishing scams.  This kind
of risk is inherent to all redirection-based protocols, including
GNAP when used in this way.
Paragraph (version B):
When talking to a new or unknown AS, a client instance might want to
check the URL from the interaction "start" against a blocklist and
warn the end-user before redirecting them.  Many client instances
will provide an interstitial message prior to redirection in order to
prepare the user for control of the user experience being handed to
the domain of the AS, and such a method could be used to warn the
user of potential threats.  For instance, a rogue AS impersonating a
well-known service provider.  Client software can also prevent this
by managing an allowlist of known and trusted AS's.
Paragraph (version B):
Alternatively, an attacker could start a GNAP request with a known
and trusted AS but include their own attack site URL as the callback
for the "finish" method.  The attacker would then send the
interaction "start" URL to the victim and get them to click on it.
Since the URL is at the known AS, the victim is inclined to do so.
The victim will then be prompted to approve the attacker's
application, and in most circumstances the victim will then be
redirected to the attacker's site whether or not the user approved
the request.  The AS could mitigate this partially by using a
blocklist and allowlist of interaction "finish" URLs during the
client instance's initial request, but this approach can be
especially difficult if the URL has any dynamic portion chosen by the
client software.  The AS can couple these checks with policies
associated with the client instance that has been authenticated in
the request.  If the AS has any doubt about the interaction finish
URL, the AS can provide an interstitial warning to the end-user
before processing the redirect.
Paragraph (version B):
Ultimately, all protocols that use redirect-based communication
through the user's browser are susceptible to having an attacker try
to co-opt one or more of those URLs in order to harm the user.  It is
the responsibility of the AS and the client software to provide
appropriate warnings, education, and mitigation to protect end users.
Paragraph (version B):
Identity assertions can be used in GNAP to convey subject
information, both from the AS to the client instance in a response-
subject and from the client instance to the AS in a request-subject.
In both of these circumstances, when an assertion is passed in GNAP,
the receiver of the assertion needs to parse and process the
assertion.  As assertions are complex artifacts with their own syntax
and security, special care needs to be taken to prevent the assertion
values from being used as an attack vector.
Paragraph (version B):
All assertion processing needs to account for the security aspects of
the assertion format in use.  In particular, the processor needs to
parse the assertion from a JSON string object, and apply the
appropriate cryptographic processes to ensure the integrity of the
assertion.
Paragraph (version B):
For example, when SAML 2 assertions are used, the receiver hast to
parse an XML document.  There are many well-known security
vulnerabilities in XML parsers, and the XML standard itself can be
attacked through the use of processing instructions and entity
expansions to cause problems with the processor.  Therefore, any
system capable of processing SAML 2 assertions also needs to have a
secure and correct XML parser.  In addition to this, the SAML 2
specification uses XML Signatures, which have their own
implementation problems that need to be accounted for.  Similar
requirements exist for OpenID Connect's ID token, which is based on
the JSON Web Token (JWT) format and the related JSON Object Signing
And Encryption (JOSE) cryptography suite.