Section 3 says [[ provide guidance on how to perform matching ]]. I can write the guidance on performing redirect URI matching, but it varies per profile.
User-Agent profile with registered client: matching is critical, MUST verify is appropriate Web server profile with client secret you trust: matching is not critical. Matching provides some extra security. MAY is appropriate. MUST is really bad, since it prevents clients from moving redirect URIs. Any profile where you don't trust the client secret (e.g. installed apps): Redirect URI matching is useless. SHOULD NOT is appropriate. So this is another case where the client needs to pass some indicator to the server (either via type= parameter, or as policy associated with client_id) of the environment in which it is running. The type parameter needs to signal: - how the authorization server passes data (fragment or query string) - what data is passed (access token, or just verification code) Here's some proposed language on redirect URI matching. New Section 3.1: Overview of Callback URL Authentication The OAuth 2 protocol distributes authorization credentials to web-based applications by redirecting the user-agent to the client with some form of authorization credential on the URL. The authorization credential is either an access token, or a authorization code. In either case, authenticating the URL to which the credential is returned is critical to the security of the protocol. Credentials returned on redirect URLs may leak in several ways: - Referer headers sent by the browser to untrusted third-party web sites - open redirectors - web server log files - browser history Authorization servers have several techniques available for authenticating callback URLs and defending against those leaks: - using client authentication credentials to authenticate callback URLs - callback URL white-listing - passing authorization credentials on URI fragments - issuing short-lived credentials to ease recovery in the event of compromise 3.1.1 Authorization Policy In certain circumstances the Authorization Server is not able to perfectly authenticate the callback URL. For example, multiple installed applications may use the same callback URL, and there is no way for the Authorization Server to reliably distinguish among them. Authorization Servers deal with this ambiguity by choosing different policies on when to issue authorization credentials. If the authorization server is able to authenticate the callback URL with a high degree of confidence - the authorization server MAY decline to prompt the user to grant authorization, immediately rejecting the authorization request. - the authorization server MAY issue an authorization credential after prompting the user. - the authorization server MAY issue a new authorization credential without prompting the user, if the authorization server knows that the user has previously approved this client. If the authorization server is not able to authenticate the callback URL: - the authorization server MAY decline to prompt the user to grant authorization, immediately rejecting the authorization request. - the authorization server MAY issue an authorization credential after prompting the user. - the authorization server MUST NOT issue an authorization credential without prompting the user. 3.1.2 Callback URL Authentication Techniques Client Credentials MAY be used to authenticate callback URLs. If an Authorization Server wishes to authenticate callback URLs with client credentials, all of the following conditions MUST be met: - the client credentials MUST have been issued to a web application with a server-side component. - the Authorization Server MUST believe that the client credentials are stored securely. - the Authorization Server MUST return only an authorization code to the callback URL. An access token MUST NOT be returned. In all other circumstances, the Authorization Server MUST use callback URL white-listing to authenticate callback URLs. However, appropriate callback URL white-listing varies for different client environments. There are various techniques for callback URL white-listing. The list in this document is not exhaustive, and Authorization Servers MAY implement other techniques at their discretion. This document will consider the following approaches: - domain white-listing Authorization Servers white-list entire domains, e.g. '*.example.com'. Authorization servers may include the protocol in this white-list, e.g. 'all https web sites on *.example.com'. Any page on any host in that domain is accepted. - host white-listing Authorization Servers white-list entire hosts, e.g. 'www.example.com'. Authorization servers may include the protocol in the white-list, e.g. 'https://www.example.com'. Any page on that host is accepted. - path white-listing Authorization Servers white-list specific paths on a particular host, e.g. 'https://www.example.com/path'. Any page beneath that path is accepted. - page white-listing Authorization Servers white-list a specific page on a particular host, e.g. 'https://www.example.com/path/page'. The query string and URI fragment may vary, but all other components of the URL are fixed and must match that page. - full URL white-listing Authorization Servers white-list a specific URL, e.g. 'https://www.example.com/path/page?query'. Any callback URL that does not completely match that URL is rejected. The following sections offer guidance to Authorization Servers and Client developers on how to handle callback URL authentication. For better security, Authorization Servers and Clients should rely on a combination of client credentials and callback URL white-listing to authenticate callback URLs. Section 3.1.3 Secure Callback URLs for the Web Server Profile Client application developers using the web server profile should take care that their callback URLs preserve the security of the profile. Callback URL pages MUST NOT link or or redirect to untrusted content from those pages, since the authorization code may leak in the referer header. Callback URL pages MUST NOT forward the authorization code to an untrusted page. Callback URL pages SHOULD redirect to a trusted page immediately after receiving the authorization code in the URL. This prevents the authorization code from remaining in the browser history, or from inadvertently leaking in a referer header. Callback URL pages SHOULD NOT log the authorization code. Callback URL pages SHOULD be CSRF protected. (TODO: dig up the language in OAuth 1.0a, it was pretty good, I think...) Section 3.1.4 Callback URL Authentication for the Web Server Profile The web server profile returns an authorization code on the callback URL. Authorization codes returned on callback URLs are very prone to leaking in referer headers, open redirectors, web server log files, and browser history. Authorization Servers MAY omit callback URL white-listing, but only if they are using client credentials to authenticate callback URLs. If client credentials are being used, any type of callback URL white-listing will improve security. Different types of white-listing provide different levels of security. - domain- and host- whitelisting Domain and host white-listing rules are very broad, and so are very vulnerable to the leaks discussed in section 3.1. Domain- and host- white-listing MUST NOT be used alone. Domain and host white-listing MAY be used in combination with using client credentials to authenticate callback URLs. - path white-listing Path white-listing is somewhat broad, and may be vulnerable to the leaks discussed in section 3.1. Path white-listing MUST NOT be used alone. Path white-listing MAY be used in combination with using client credentials to authenticate callback URLs. When using path white-listing, Authorization servers MUST defend against directory traversal attacks by canonicalizing the path. Appropriate path canonicalization algorithms vary for different types of web-servers, e.g. "\..\" may represent a parent directory in some web servers, and not in others. - page and URL white-listing Page and URL white-listing are very specific, but may still be vulnerable to some of the leaks discussed in section 3.1 if the callback URL page does not follow the security recommendations in section 3.1.3. These types of white-listing MAY be used alone, or in combination with client credentials to authenticate callback URLs. When full URL white-listing is used, Authorization Servers MUST allow the "state" query parameter to vary. Section 3.1.4 Secure Callback URLs for the User-Agent Profile Client application developers using the user-agent profile should take care that their callback URLs preserve the security of the profile. Because the user-agent profile returns an access token on the URI fragment, many types of leaks are less likely. However, incorrect code can still leak the authorization credentials. Callback URL pages MUST NOT forward the access token or authorization code to an untrusted page. Callback URLs rendered in a top-level browser window cannot prevent the access token from remaining in the browser history. Whenever possible, client applications SHOULD use an iframe to receive callbacks so that the access token does not appear in the browser history. [[Note that Authorization Servers SHOULD NOT allow their approval pages to be iframed due to the risk of click-jacking attacks, so this only works for immediate mode. Browser security gets complicated.]] If callback URLs must be rendered in a top-level browser window, client applications SHOULD redirect immediately after receiving the callback URL to remove the access token from the URL bar. This prevents the user from inadvertently copying their access token. Callback URL pages SHOULD be CSRF protected. (TODO: dig up the language in OAuth 1.0a, it was pretty good, I think...) Section 3.1.4 Callback URL Authentication for the User-Agent profile Because the user-agent profile returns an access token on the callback URL, client credentials cannot be used to authenticate the callback URL. Callback URL white-listing is the only possible way to authenticate the callback URL. However, because the authorization credentials are always returned on the URL fragment, the opportunity for leaking credentials via referer headers and open redirectors is reduced. Different types of white-listing provide different levels of security. - domain- white-listing Domain white-listing is very broad. Domain white-listing MUST NOT be used, because of the risk of malicious code running under some host in the domain. - host- white-listing Host white-listing is very broad. Authorization servers should be conservative in choosing which hosts they trust, but host white-listing MAY be used. - path white-listing Path white-listing is somewhat broad. Path white-listing MAY be used. When using path white-listing, Authorization servers MUST defend against directory traversal attacks by canonicalizing the path. Appropriate path canonicalization algorithms vary for different types of web-servers, e.g. "\..\" may represent a parent directory in some web servers, and not in others. - page and URL white-listing Page and URL white-listing are very specific. These types of white-listing MAY be used When full URL white-listing is used, Authorization Servers MUST allow the "state" query parameter to vary. Cheers, Brian _______________________________________________ OAuth mailing list OAuth@ietf.org https://www.ietf.org/mailman/listinfo/oauth
