Last Call Review of draft-ietf-oauth-introspection-08
review-ietf-oauth-introspection-08-secdir-lc-kent-2015-06-05-00

I
        reviewed this document as part of the security
        directorate's ongoing effort to review all IETF documents being
        processed by
        the IESG.

  

These comments
        were written
        with the intent of improving security requirements and
        considerations in IETF
        drafts.

  

Comments not
        addressed in last
        call may be included in AD reviews during the IESG review.

  

Document editors and WG
        chairs should treat
        these comments just like any other last call comments.




 




This
        document describes an API for use with OAuth 2.0. The API
        enables the recipient
        of a token to query an authorization server to determine the set
        of metadata
        presented to the server (by the OAuth client) when the token was
        issued. This
        API is intended to overcome the lack of a standard way to convey
        token metadata
        in the OAuth 2.0 context.




 




I
        didn’t find any significant security problems with the document,
        but there are
        a number of places where the exposition needs improvement.




 




Specific
        comments




 




Section
        2




 




The text
        says:

   




 




The
        introspection endpoint
        MUST be protected by a transport-layer security mechanism as
        described in
        Section 4.




 




It
        might be clearer to say here that the token endpoint MUST
        communicate security
        with the introspection endpoint, and that TLS 1.2 is the
        mandatory-to-implement
        mechanism for such security. Also, the text should be clearer
        about the
        relationship between an authorization server and an
        introspection endpoint. In
        some places the two terms seem to be used interchangeably.




 




Section
        2.1




 




The
        texts says:




 




The endpoint
        MAY allow
        other parameters to provide further context to the query.

  




 




How about:




 




The endpoint
        MAY 

accept

 other
        parameters to provide
        further context to the query.

  




 




How does a
        protected
        resource know which other parameters an introspection endpoint
        requires/accepts?




 




 




This
        section mandates (MUST) protection against “unauthorized token
        scanning” but
        mandates no standard way to do so. [Also, when would a scanning
        “attack” be
        authorized ;-)] 




 




 




The text
        says:




 




For example,
        the following
        example shows a protected resource calling the token
        introspection endpoint to
        query about an OAuth 2.0 bearer.




 




How about:




 




For example,
        the following
        example shows a protected resource calling the token
        introspection endpoint to
        query about an OAuth 2.0 bearer 

token

.




 




 




Section 2.2




 




He text says:




 




   

The authorization server MAY respond
        differently to
        different




   

protected resources making
        the same
        request.

  

For instance,
        an




   

authorization server MAY
        limit which scopes
        from a given token are




   

returned for each
        protected resource in order
        to prevent protected




   

resources from learning
        more about the
        larger network than is




   

necessary for their
        function.




 




How about:




 




   

An

 authorization server MAY respond
        differently to
        different




   

protected resources making
        the same
        request.

  

For instance,
        an




   

authorization server MAY
        limit which scopes
        from a given token are




   

returned 

to

 each protected resource in order to prevent 

a 

protected




   

resources from learning
        more about the
        larger network than is




   

necessary for 

its

 

operation

.




 




 




Section 3.1




 




Experience
        suggests a
        longer review period is appropriate, e.g., to accommodate
        holidays, vacations,
        etc.




 




The text
        says:




 




IANA must
        only accept
        registry updates from the Designated Expert(s)




and should
        direct all
        requests for registration to the review mailing




list.




 




How about:




 




IANA 

MUST

 accept registry updates 

only


        from the Designated Expert(s)




and 

SHOULD

 direct all requests for registration to the
        review mailing




list.




 




Section 3.1.1




 




If a proposed
        Name matches
        one already registered as per 7519, ought it not have an
        “equivalent” (vs.
        “comparable”) definition if it is to be accepted?




 




 




Section 4




 




The text
        lists four checks
        to be performed by an authorization server, yet the introduction
        to this list
        says “For instance:” A more normative introduction would seem
        appropriate here.
        I realize that the text says that not all of these checks may be
        applicable in
        all OAuth 2.0 contexts, but since each check begins with “If the
        token …” isn’t
        that a sufficient caveat?




 




The text
        says:




 




If an
        authorization server
        fails to perform any applicable check, the




resource
        server could make
        an errant security decision based on that




response.

  




 




How about: 




 




If an
        authorization server
        fails to perform any applicable check, the




resource
        server could make
        an 

erroneous


        security decision based
        on that response.

  




 




 




The text
        says:




 




per RFC 6125
        [RFC6125].




 




How about:




 




as specified
        in [RFC6125].




 




 




The
        discussion of
        introspection endpoint response caching seems to omit a simple,
        useful
        heuristic. Since the expiration time for a token is an optional
        parameter in
        the response, why not say that IF this parameter is present, the
        response MUST
        NOT be cached beyond that time?




 




 




Section 5




 




This section
        says: “One
        way to limit disclosure is to require




authorization
        to call the
        introspection endpoint and to limit calls




to only
        registered and
        trusted protected resource servers.” But 

 




Section 4
        says: “… the
        authorization server MUST require authentication of protected
        resources that
        need to access the introspection endpoint and SHOULD require
        protected
        resources to be specifically authorized to call the
        introspection endpoint.”

  

It
        seems that the requirement imposed in
        Section 4 already mandate what is merely suggested in Section 5.