Internet DRAFT - draft-tsitkov-audit

draft-tsitkov-audit







Network Working Group                                   Zh. Tsitkov, Ed.
Internet-Draft                                                       MIT
Intended status: Informational                          October 14, 2014
Expires: April 17, 2015


                           Audit in OAuth 2.0
                         draft-tsitkov-audit-00

Abstract

   This specification is an effort to provide guidelines for
   implementing the Audit functionality for OAuth 2.0 enabled
   environments.  The data of interest for the OAuth 2.0 audit includes
   permissions, scopes, policies and other authorization and
   authentication related information.  It can be used by user agents
   and authorization services for fast violation response, credential
   revocation, or by government agencies and various institutions for
   forensic analysis.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on April 17, 2015.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must



Tsitkov                  Expires April 17, 2015                 [Page 1]

Internet-Draft                    Audit                     October 2014


   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   3
   3.  Audit ID  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Audit log parameters  . . . . . . . . . . . . . . . . . . . .   4
   5.  Event selection . . . . . . . . . . . . . . . . . . . . . . .   5
   6.  Audit vs privacy  . . . . . . . . . . . . . . . . . . . . . .   5
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   8.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .   6
   9.  Issues  . . . . . . . . . . . . . . . . . . . . . . . . . . .   6
   10. Normative References  . . . . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   This specification is an effort to provide guidelines for
   implementing the Audit functionality for OAuth 2.0 [OAuth2] enabled
   environments.  The data of interest for the OAuth 2.0 audit includes
   permissions, scopes, policies and other authorization and
   authentication related information.  It can be used by user agents
   and authorization services for fast violation response, credential
   revocation, or by government agencies and various institutions for
   forensic analysis, and similar purposes.

   The intention of this specification is:

   o  to address the quality of the content of audit logs.  This is done
      by identifying the mandatory, recommended and optional auditable
      information from the OAuth 2.0 perspective;

   o  to improve audit log processing.  This is achieved by introducing
      an audit identifier that simplifies log querying;

   o  to encourage all OAuth 2.0 participants to store and protect
      information that is useful for the audit.

   The goal of this proposal is to provide a high quality feed to
   various audit processing facilities.  Identifying mechanisms of how
   the logs are processed is outside the scope of this document.  It can
   be done dynamically, and, for example, trigger that tokens to be
   revoked.  It can be done by resource owner's Audit Agent.  It can be
   done off-line when audit analysis is performed.




Tsitkov                  Expires April 17, 2015                 [Page 2]

Internet-Draft                    Audit                     October 2014


2.  Notational Conventions

   The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
   'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
   document are to be interpreted as described in [RFC2119].

   Unless otherwise noted, all the protocol properties and values are
   case sensitive.

3.  Audit ID

   To optimize audit log handling this document introduces an Audit ID
   (audit_id) an identifier with the following properties:

   o  It is unique and stays unchanged for a given OAuth 2.0 end-to-end
      communication;

   o  It is generated as part of OAuth 2.0 processing;

   o  It is protected against data tampering;

   o  It is available to all OAuth 2.0 participants to be recorded for
      their audit needs;

   o  It can be passed to downstream modules.

   The audit_id becomes useful when, for example, one of the OAuth 2.0
   participants (most likely resource server or authorization server)
   suspects some malicious activity.  It can then request the other
   participants to provide information from their audit logs that
   corresponds to the particular audit_id and, based on the acquired
   information, perform further analysis of the suspected attack.
   Alternatively, suspecting party can issue warning to the other
   participants about the suspicious activity associated with the
   particular audit_id.  In addition, in more static use-case, such as
   forensic analysis, the audit identifier makes it possible and simple
   to find out who was responsible for the violation, whether it was due
   to the wrongful resource registration, misinterpreting the policies,
   etc.

   The audit identifier can be an alphanumeric string, or a JSON
   structure.  It can be randomly generated, or constructed out of some
   unique parameters, such as components of the tokens, session ids,
   timestamps.

   The uniqueness of the audit_id is important especially in the cases
   when audit logs are processed dynamically.  Since randomizers on
   Clients or resource server's (RS) are commonly weaker and less



Tsitkov                  Expires April 17, 2015                 [Page 3]

Internet-Draft                    Audit                     October 2014


   collision-resistant when compared to authorization server's (AS)
   randomizers, in most environments, it should be the responsibility of
   AS to generate a high quality "strong" audit id.  However, it should
   be allowed for the client or resource server to have their own audit
   id's for internal bookkeeping.  These identifiers can be passed to
   the authorization server as part of the initial request and AS should
   include it in the reply messages together with the "strong" AS-
   selected audit id.

   Authorization server may adopt any audit identifier coming from the
   outside of AS as a "strong" audit ID if it believes that it is a high
   quality identifier.

   It is desirable for resource server, client and authorization server
   to record audit related information for all communications, at least
   for the mandatory set of parameters.  It makes analysis of audit
   trails more effective.

   The audit ID can be passed to the downstream modules, such as OIDC
   identity provider.  The latter can use it for its own audit needs.

4.  Audit log parameters

   It is considered a good practice to keep the audit log concise.
   Overloading logs with unnecessary information comes with the burden
   of extra storage allocation and protection, and less effective
   information processing (both time-wise and resource-wise).

   The following are the recommended parameters that, when applicable,
   should be included in the OAuth 2.0 audit logs for AS, RS and client.
   All security sensitive information should be stripped and not logged.
   The implementers have the opportunity to customize audit logs by
   extending auditable parameters and events.

   audit_id
         A non-modifiable identifier that is used to track all
         participants on all stages of the OAuth 2.0 communication;

   event_type
         A type of event.  For example, "permissions problem";

   event_category
         Type of action performed when audit is generated.  For example,
         "resource server processing";

   timestamp
         A timestamp when event occurred;




Tsitkov                  Expires April 17, 2015                 [Page 4]

Internet-Draft                    Audit                     October 2014


   event_outcome
         Indicates whether the event is reported on success or failure;

   endpoint_uri
         Endpoint URI;

   source
         Code specifying the type of source where event originated;

   permissions
         Requested, granted permissions including resource id, lifetime,
         scopes, and other access attributes;

   token_status
         Full token status, including validity periods, corresponding
         refresh tokens, etc

   policies
         Policies.

   The content of the audit logs can be configurable.  If, for example,
   the performance or storage are a concern, the administrator may
   choose to log only basic mandatory information.  However, if this is
   not the case, or under violation alert, more detailed audit
   information may be useful.  In this case the administrator may switch
   the audit configuration from the basic level to the detailed.  There
   should be well defined mandatory set of parameters.

5.  Event selection

   In general, all AS-RS , Client-RS, Client-AS interactions, successful
   or not, should be recorded in the audit log files.  This includes
   permission requests, token issuance, token introspection, etc.

6.  Audit vs privacy

   Privacy and auditing are closely related.  As it has been discussed
   in [Privacy-Considerations], audit trail can help to identify the
   misuse of information, such as unauthorized secondary use of data.
   On the other hand, stored audit logs may be compromised, data can be
   collected and analyzed.  To address the privacy risks one should make
   sure that the audit system is simple, transparent, and unambiguous.
   Generally, audit designers should minimize the exposure of privacy
   related information in the logs.  Also, it should always be clear, if
   the audit logs are jeopardized, what privacy related information has
   leaked.





Tsitkov                  Expires April 17, 2015                 [Page 5]

Internet-Draft                    Audit                     October 2014


   One should notice, that introducing audit_id into audit log in OAuth
   2.0 enabled environments does not add any privacy related concerns.

7.  IANA Considerations

   This document makes no request of IANA.

8.  Acknowledgments

   TBD

9.  Issues

10.  Normative References

   [OAuth2]   Hardt, D., "The OAuth 2.0 Authorization Framework",
              October 2012, <http://tools.ietf.org/html/rfc6749>.

   [Privacy-Considerations]
              Cooper, A., "Privacy Considerations for Internet
              Protocols", July 2013,
              <http://tools.ietf.org/html/rfc6973>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

Author's Address

   Zhanna Tsitkov (editor)
   MIT

   Email: tsitkova@mit.edu



















Tsitkov                  Expires April 17, 2015                 [Page 6]