Internet DRAFT - draft-tsitkov-oauth-audit
draft-tsitkov-oauth-audit
Network Working Group Zh. Tsitkov
Internet-Draft MIT
Intended status: Informational January 21, 2015
Expires: July 25, 2015
Audit in OAuth 2.0
draft-tsitkov-oauth-audit-02
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 July 25, 2015.
Copyright Notice
Copyright (c) 2015 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 July 25, 2015 [Page 1]
Internet-Draft Audit January 2015
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. Privacy and audit logs protection . . . . . . . . . . . . . . 6
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7
9. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
10. Normative References . . . . . . . . . . . . . . . . . . . . 7
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 July 25, 2015 [Page 2]
Internet-Draft Audit January 2015
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 does not expose security and privacy sensitive information;
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 the history 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.
Also, since access to audit records is a security mediated event, any
viewing, examination or querying of the logs is protected by access
controls and audit logging continues to happen. The presence of
audit identifiers in the logs produced as result of trail's querying
helps to identify who has accessed the records associated with the
particular audit_id.
Tsitkov Expires July 25, 2015 [Page 3]
Internet-Draft Audit January 2015
The audit identifier can be an alphanumeric string, or a JSON
structure. It can be randomly generated opaque identifier, or
constructed out of some unique parameters, such as "state" request
parameter, components of the tokens, session identifiers, timestamps.
One should consider keeping these identifiers small as it makes audit
trails more compact, their recording faster, and audit log lookups
more efficient.
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
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;
Tsitkov Expires July 25, 2015 [Page 4]
Internet-Draft Audit January 2015
event_type
Type of event. For example, "Authorization request";
timestamp
Timestamp when event occurred;
event_outcome
Indicates whether the event is reported on success or failure;
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);
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.
Tsitkov Expires July 25, 2015 [Page 5]
Internet-Draft Audit January 2015
The following parameters SHOULD be excluded from the audit logs for
the security and privacy reasons: TODO.
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 interactions between authorization server, resource
server, resource owner and client, successful or not, SHOULD be
recorded in the audit logs. When examining audit records, this
allows to reconstruct the sequence of events and to determine how the
system has arrived into a particular state.
The following events, at minimum, should be included into the audit
trails: registration, authorization, redirection and access token
requests and responses; token revocation and introspection.
6. Privacy and audit logs protection
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 system 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.
In some deployments encrypting the whole or partial content of the
audit logs presents itself as a viable option for record protection
from unauthorized access. The design of such audit systems is out of
scope of this document.
The integrity protection of the audit records can be achieved using
digital signing, calculating digest and storing it securely and
similar approaches. TODO.
Tsitkov Expires July 25, 2015 [Page 6]
Internet-Draft Audit January 2015
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
MIT
Email: tsitkova@mit.edu
Tsitkov Expires July 25, 2015 [Page 7]
