Network Working Group Zh. Tsitkov, Ed. Internet-Draft MIT Intended status: Informational December 8, 2014 Expires: June 11, 2015 Audit in OAuth 2.0 draft-tsitkov-oauth-audit-01 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 scopes, permissions, policies and other authorization and authentication related information. It can be used by resource and authorization servers for detecting security-related problems in real time and fast violation response, or by government agencies and various institutions for after-the-fact forensic and compliance 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 June 11, 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 Tsitkov Expires June 11, 2015 [Page 1] Internet-Draft Audit December 2014 to this document. Code Components extracted from this document must 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 . . . . . . . . . . . . . . . . . . . . . . . 6 6. Audit vs privacy . . . . . . . . . . . . . . . . . . . . . . 6 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6 9. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 10. Normative References . . . . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 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 resource and authorization servers for intrusion detection and fast violation response, or by government agencies and businesses for forensic analysis, verification of legal compliances, 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 trails processing. This is achieved by introducing an audit identifier that simplifies log querying; o to encourage all OAuth 2.0 participants to securely 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 June 11, 2015 [Page 2] Internet-Draft Audit December 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 identifier Audit ID (audit_id) 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; 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 and take an action to address the problem. 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 security problem examination involving the reconstruction of events, the audit identifier makes it possible and simple to find out who was responsible for the violation, whether it was due to resource registration or misinterpreting the policies, implementation flaws, 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 "state" request parameter, 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 Tsitkov Expires June 11, 2015 [Page 3] Internet-Draft Audit December 2014 clients or resource server's (RS) are commonly weaker and less 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 identifier. 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. 4. Audit log parameters It is considered a good practice to keep the audit trails 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 or privacy sensitive information should be either stripped and not logged or, alternatively, encrypted to preserve confidentiality. The implementers have the opportunity to customize audit logs by extending auditable parameters and events. The following should be considered as mandatory parameters: audit_id Non-modifiable identifier that is used to track all participants on all stages of the OAuth 2.0 communication; event_type Type of event. For example, "User consent"; timestamp Timestamp when event occurred; event_outcome Indicates whether the event is reported on success or failure; Tsitkov Expires June 11, 2015 [Page 4] Internet-Draft Audit December 2014 endpoint_uri URI of the authorization server; source Code specifying the type of source where event originated. client_id Unique identifier created for this client during registration; state Local "state" parameter provided by client in the authorization request (if applicable); resource_id Unique resource server identifier; redirect_uri URI used for access token; The following should be considered as optional parameters: event_category Type of action performed when audit is generated. For example, "resource server processing"; grand_type Type of grant that was used; requested_scopes Full list of the requested scopes; granted_scopes List of the granted scopes; token_status Full token status, including its value, type, validity periods, refresh token value. policies Policies that affected authorization decision. 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. Tsitkov Expires June 11, 2015 [Page 5] Internet-Draft Audit December 2014 5. Event selection In general, all interections between authorization server, resource server, resource owner and client, 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 well protected, 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. One should notice, that introducing audit_id into audit log in OAuth 2.0 enabled environments does not add any privacy related risks. 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, . [Privacy-Considerations] Cooper, A., "Privacy Considerations for Internet Protocols", July 2013, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Tsitkov Expires June 11, 2015 [Page 6] Internet-Draft Audit December 2014 Author's Address Zhanna Tsitkov (editor) MIT Email: tsitkova@mit.edu Tsitkov Expires June 11, 2015 [Page 7]