diff options
Diffstat (limited to 'chromium/docs/website/site/developers/design-documents/http-authentication')
2 files changed, 0 insertions, 408 deletions
diff --git a/chromium/docs/website/site/developers/design-documents/http-authentication/index.md b/chromium/docs/website/site/developers/design-documents/http-authentication/index.md deleted file mode 100644 index e9009d84d4f..00000000000 --- a/chromium/docs/website/site/developers/design-documents/http-authentication/index.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -page_name: http-authentication -title: HTTP authentication ---- - -As specified in [RFC 2617](http://www.ietf.org/rfc/rfc2617.txt), HTTP supports -authentication using the WWW-Authenticate request headers and the Authorization -response headers (and the Proxy-Authenticate and Proxy-Authorization headers for -proxy authentication). - -**Supported authentication schemes** - -> Chrome supports four authentication schemes: Basic, Digest, NTLM, and -> Negotiate. Basic, Digest, and NTLM are supported on all platforms by default. -> Negotiate is supported on all platforms except Chrome OS by default. - -> The Basic and Digest schemes are specified in [RFC -> 2617](http://www.ietf.org/rfc/rfc2617.txt). NTLM is a Microsoft proprietary -> protocol. The Negotiate (or SPNEGO) scheme is specified in [RFC -> 4559](http://www.ietf.org/rfc/rfc4559.txt) and can be used to negotiate -> multiple authentication schemes, but typically defaults to either Kerberos or -> NTLM. - -> The list of supported authentication schemes may be overridden using the -> [AuthSchemes](/administrators/policy-list-3#AuthSchemes) policy. See [this -> page](/administrators) for details on using administrative policies. - -**Choosing an authentication scheme** - -> When a server or proxy accepts multiple authentication schemes, our network -> stack selects via HttpAuth::ChooseBestChallenge() the authentication scheme -> with the highest score: - - * Basic: 1 - * Digest: 2 - * NTLM: 3 - * Negotiate: 4 - -> The Basic scheme has the lowest score because it sends the username/password -> unencrypted to the server or proxy. - -> So we choose the most secure scheme, and we ignore the server or proxy's -> preference, indicated by the order in which the schemes are listed in the -> WWW-Authenticate or Proxy-Authenticate response headers. This could be a -> source of compatibility problems because [MSDN documents that "WinInet chooses -> the first method it -> recognizes."](http://msdn.microsoft.com/en-us/library/aa384220%28VS.85%29.aspx) -> Note: In IE7 or later, WinInet chooses the first *non-Basic* method it -> recognizes. - -**Integrated Authentication** - -> With Integrated Authentication, Chrome can authenticate the user to an -> Intranet server or proxy without prompting the user for a username or -> password. It does this by using cached credentials which are established when -> the user initially logs in to the machine that the Chrome browser is running -> on. Integrated Authentication is supported for Negotiate and NTLM challenges -> only. - -> Due to potential attacks, Integrated Authentication is only enabled when -> Chrome receives an authentication challenge from a proxy, or when it receives -> a challenge from a server which is in the permitted list. - -> This list is passed in to Chrome using a comma-separated list of URLs to -> Chrome via the -> [AuthServerWhitelist](/administrators/policy-list-3#AuthServerWhitelist) -> policy setting. For example, if the AuthServerWhitelist policy setting was: - -> > \*example.com,\*foobar.com,\*baz - -> ...then Chrome would consider that any URL ending in either 'example.com', -> 'foobar.com', or 'baz' is in the permitted list. Without the '\*' prefix, the -> URL has to match exactly. - -> In **==Windows only==**, if the AuthServerWhitelist setting is not specified, -> the permitted list consists of those servers allowed by the Windows Zones -> Security Manager (queried for URLACTION_CREDENTIALS_USE). By default, this -> includes servers in the Local Machine or Local Intranet security zones. For -> example, when the host in the URL includes a "." character, by default it is -> outside the Local Intranet security zone). This behavior matches Internet -> Explorer and other Windows components. - -> If a challenge comes from a server outside of the permitted list, the user -> will need to enter the username and password. - -> Starting in Chrome 81, Integrated Authentication is [disabled by default for -> off-the-record (Incognito/Guest) -> profiles](https://bugs.chromium.org/p/chromium/issues/detail?id=458508#c62), -> and the user will need to enter the username and password. - -**Kerberos SPN generation** - -> When a server or proxy presents Chrome with a Negotiate challenge, Chrome -> tries to generate a Kerberos SPN (Service Principal Name) based on the host -> and port of the original URI. Unfortunately, the server does not indicate what -> the SPN should be as part of the authentication challenge, so Chrome (and -> other browsers) have to guess what it should be based on standard conventions. - -> The default SPN is: HTTP/<host name>, where <host name> is the -> canonical DNS name of the server. This mirrors the SPN generation logic of IE -> and Firefox. - -> The SPN generation can be customized via policy settings: - -> * [DisableAuthNegotiateCnameLookup](/administrators/policy-list-3#DisableAuthNegotiateCnameLookup) - determines whether the original hostname in the URL is used rather - than the canonical name. If left unset or set to false, Chrome - uses the canonical name. -> * [EnableAuthNegotiatePort](/administrators/policy-list-3#EnableAuthNegotiatePort) - determines whether the port is appended to the SPN if it is a - non-standard (not 80 or 443) port. If set to true, the port is - appended. Otherwise (or if left unset) the port is not used. - -> For example, assume that an intranet has a DNS configuration like - -> auth-a.example.com IN CNAME auth-server.example.com - -> auth-server.example.com IN A 10.0.5.3 - -> <table> -> <tr> -> <td> URL</td> -> <td> Default SPN </td> -> <td> With DisableAuthNegotiateCnameLookup</td> -> <td> With EnableAuthNegotiatePort </td> -> </tr> -> <tr> -> <td> http://auth-a</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-a</td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> <tr> -> <td> https://auth-a</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-a </td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> <tr> -> <td> http://auth-a:80</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-a</td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> <tr> -> <td> https://auth-a:443</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-a</td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> <tr> -> <td> http://auth-a:4678</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-a</td> -> <td> HTTP/auth-server.example.com:4678</td> -> </tr> -> <tr> -> <td> http://auth-a.example.com</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-a.example.com</td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> <tr> -> <td> http://auth-server</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-server</td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> <tr> -> <td> http://auth-server.example.com</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-server.example.com</td> -> <td> HTTP/auth-server.example.com</td> -> </tr> -> </table> - -**Kerberos Credentials Delegation (Forwardable Tickets)** - -> Some services require delegation of the users identity (for example, an IIS -> server accessing a MSSQL database). By default, Chrome does not allow this. -> You can use the -> [AuthNegotiateDelegateWhitelist](/administrators/policy-list-3#AuthNegotiateDelegateWhitelist) -> policy to enable it for the servers. - -> Delegation does not work for proxy authentication. - -### **Negotiate external libraries** - -> On Windows, Negotiate is implemented using the SSPI libraries and depends on -> code in secur32.dll. - -> On Android, Negotiate is implemented using an external Authentication app -> provided by third parties. Details are given in [Writing a SPNEGO -> Authenticator for Chrome on -> Android](/developers/design-documents/http-authentication/writing-a-spnego-authenticator-for-chrome-on-android). -> The AuthAndroidNegotiateAccountType policy is used to tell Chrome the Android -> account type provided by the app, hence letting it find the app. - -> On other platforms, Negotiate is implemented using the system GSSAPI -> libraries. The first time a Negotiate challenge is seen, Chrome tries to -> dlopen one of several possible shared libraries. If it is unable to find an -> appropriate library, Chrome remembers for the session and all Negotiate -> challenges are ignored for lower priority challenges. - -> The [GSSAPILibraryName](/administrators/policy-list-3#GSSAPILibraryName) -> policy can be used to specify the path to a GSSAPI library that Chrome should -> use. - -> Otherwise, Chrome tries to dlopen/dlsym each of the following fixed names in -> the order specified: - - * OSX: libgssapi_krb5.dylib - * Linux: libgssapi_krb5.so.2, libgssapi.so.4, libgssapi.so.2, - libgssapi.so.1 - -> Chrome OS follows the Linux behavior, but does not have a system gssapi -> library, so all Negotiate challenges are ignored. - -**Remaining work** - -* Support GSSAPI on Windows \[for MIT Kerberos for Windows or - Heimdal\] -* Offer [a policy to disable Basic authentication - scheme](https://bugs.chromium.org/p/chromium/issues/detail?id=1025002) - over unencrypted channels. - -**Questions?** - -> Please feel free to send mail to net-dev@chromium.org
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/http-authentication/writing-a-spnego-authenticator-for-chrome-on-android/index.md b/chromium/docs/website/site/developers/design-documents/http-authentication/writing-a-spnego-authenticator-for-chrome-on-android/index.md deleted file mode 100644 index f59ddacd8bd..00000000000 --- a/chromium/docs/website/site/developers/design-documents/http-authentication/writing-a-spnego-authenticator-for-chrome-on-android/index.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/http-authentication - - HTTP authentication -page_name: writing-a-spnego-authenticator-for-chrome-on-android -title: Writing a SPNEGO Authenticator for Chrome on Android ---- - -As described in [Kerberos for Chrome on -Android](https://docs.google.com/document/d/1G7WAaYEKMzj16PTHT_cIYuKXJG6bBcrQ7QQBQ6ihOcQ/edit?usp=sharing), -in Chrome M46 third parties can enable SPNEGO authentication in Chrome for -Android. To do this they must provide a SPNEGO Authenticator. This page -describes the interface between Chrome and the SPNEGO Authenticator. - -# Basics - -The SPNEGO Authenticator is provided by an Android Service. This must be -incorporated in an app, provided by the third party, installed on the user’s -device. The app is responsible for managing any accounts used for SPNEGO -authentication, and for all communication with the SPNEGO server. - -The SPNEGO Authenticator is an Android AccountAuthenticator. As such it must -follow the pattern described in -[AbstractAccountAuthenticator](http://developer.android.com/reference/android/accounts/AbstractAccountAuthenticator.html). -In particular it must implement an authenticator class derived from -AbstractAccountAuthenticator. - -The SPNEGO Authenticator must define a new account type. Its name should be -derived from the writer’s domain name (e.g. com.example.spnego). As explained in -[Kerberos for Chrome on -Android](https://docs.google.com/document/d/1G7WAaYEKMzj16PTHT_cIYuKXJG6bBcrQ7QQBQ6ihOcQ/edit?usp=sharing), -the account type must be defined to use -[customTokens](http://developer.android.com/reference/android/R.attr.html#customTokens). -The account type must support the “SPNEGO” feature -(HttpNegotiateConstants.SPNEGO_FEATURE). - -# Interface to Chrome - -Chrome finds the SPNEGO authenticator through the Android account type it -provides. This is defined by the authenticator, and passed to Chrome through the -AuthAndroidNegotiateAccountType policy. - -The interface to Chrome is through the Android account management framework, and -in particular through -[AbstractAccountManager.getAuthToken](http://developer.android.com/reference/android/accounts/AbstractAccountAuthenticator.html#getAuthToken(android.accounts.AccountAuthenticatorResponse,%20android.accounts.Account,%20java.lang.String,%20android.os.Bundle)). -Chrome, in -[org.chromium.net.HttpNegotiateConstants](https://code.google.com/p/chromium/codesearch#chromium/src/net/android/java/src/org/chromium/net/HttpNegotiateConstants.java&q=HttpNeg&sq=package:chromium&l=10), -defines some additional keys and values that are used in the arguments to -getAuthToken, and in the returned result bundle. - -## getAuthToken arguments - -When -[getAuthToken](http://developer.android.com/reference/android/accounts/AbstractAccountAuthenticator.html#getAuthToken(android.accounts.AccountAuthenticatorResponse,%20android.accounts.Account,%20java.lang.String,%20android.os.Bundle)) -is called the authTokenType will be "SPNEGO:HOSTBASED:<spn>" where -<spn> is the principal for the request. This will always be a host based -principal (in the current implementation; future versions may allow other types -of principal, but if they do so they will use a different prefix. SPNEGO -Authenticators should check the prefix). - -The options bundle will contain the keys: - - [KEY_CALLER_PID](http://developer.android.com/reference/android/accounts/AccountManager.html#KEY_CALLER_PID) - - [KEY_CALLER_UID](http://developer.android.com/reference/android/accounts/AccountManager.html#KEY_CALLER_UID) - - HttpNegotiateConstants.KEY_CAN_DELEGATE - True if delegation is allowed, - false otherwise. - -If this is the second or later round of multi-round authentication sequence it -will also contain. - - HttpNegotiateConstants.KEY_INCOMING_AUTH_TOKEN - The incoming token from the - WWW-Authenticate header, Base64 encoded. - - HttpNegotiateConstants.KEY_SPNEGO_CONTEXT - The SPNEGO context provided by - the authenticator on the previous round. This is a bundle. Chrome treats - this as an opaque object and simply preservers it between rounds. - -## getAuthToken result bundle - -The final result bundle of -[getAuthToken](http://developer.android.com/reference/android/accounts/AbstractAccountAuthenticator.html#getAuthToken(android.accounts.AccountAuthenticatorResponse,%20android.accounts.Account,%20java.lang.String,%20android.os.Bundle)) -(returned either as the return value of getAuthToken, or through the -[AccountAuthenticatorResponse](http://developer.android.com/reference/android/accounts/AccountAuthenticatorResponse.html)) -should contain the account name, account type, and token as defined in the -Android documentation. The token should be Base64 encoded. In addition the -bundle should contain the keys: - - HttpNegotiateConstants.KEY_SPNEGO_RESULT - the SPNEGO result code. This - should be one of the values defined in - [HttpNegotiateConstants](https://code.google.com/p/chromium/codesearch#chromium/src/net/android/java/src/org/chromium/net/HttpNegotiateConstants.java&q=HttpNeg&sq=package:chromium&l=10). - - HttpNegotiateConstants.KEY_SPNEGO_CONTEXT - a context to be returned to the - authenticator in the next authentication round. This is only required if - authentication is incomplete. - -# Implementation recommendations - - Each account provided by an SPNEGO Account Authenticator should correspond - to a single user principal (account) provided by single key distribution - center. - - The account authenticator should not store any passwords. Instead it should - store TGTs for the user principles, and require the users to re-enter their - passwords (or other authentication data) when their TGT expires. - - The account authenticator should keep a list of authorized applications (or - application signatures) for each account, and refuse to provide service - tokens to other applications. The list of authorized applications may be: - - Built into the account authenticator. - - Configurable by the system administrator - - Configurable by the user. In this case the account authenticator might - choose to allow the user to authorize new applications dynamically when - they first request access. - -The authenticator can get the uid of the calling app using the KEY_CALLER_UID -field of the options bundle, and then identify the requesting application using -context.getPackageManager().getNameForUid() or similar. - -This is required to ensure that malicious apps run by the user cannot use the -user’s credentials to access services in unintended ways. This is particularly -important since using the custom tokens option (as described above) disables -Android’s own signature check when getting auth tokens. - - Unless it is built into the account authenticator, the system administrator - or user will need to be able to configure the location of the key - distribution center. - -Error codes displayed in Chrome - -In addition to the error codes that can be forwarded from the authenticator app, -the following errors can be displayed by Chrome when trying to authenticate a -request: - -* ERR_MISSING_AUTH_CREDENTIALS: The account information is not usable. - It can be raised for example if the user did not log in to the - authenticator app and no eligible account is found, if the account - information can't be obtained because the current app does not have - the required permissions, or if there is more than one eligible - account and we can't obtain a selection from the user. -* ERR_UNEXPECTED: An unexpected error happened and the request has - been terminated. -* ERR_MISCONFIGURED_AUTH_ENVIRONMENT: The authentication can't be - completed because of some issues in the configuration of the app. - Some permissions may be missing. - -Please search for the **cr_net_auth** tag in logcat to have more information -about the cause of these errors. - -# Use, and testing, with Chrome - -Chrome defines [a number of policies for controlling the use of SPNEGO -authentication](/administrators/policy-list-3#HTTPAuthentication). In particular -to enable SPNEGO authentication the -[AuthServerWhitelist](/administrators/policy-list-3#AuthServerWhitelist) must -not be empty, and the -[AuthAndroidNegotiateAccountType](http://www.chromium.org/administrators/policy-list-3#AuthAndroidNegotiateAccountType) -must match the account type provided by the SPNEGO authenticator. - -To simplify testing of SPNEGO authentication Chrome on Android supports command -line options corresponding to these policies. These are -“--auth-server-whitelist=*<whitelist>*” and -“--auth-spnego-account-type=*<account type>*”. To set these, [add them to -the command line on the -device](/developers/how-tos/run-chromium-with-flags#TOC-Setting-Flags-for-Chrome-on-Android) -(requires a rooted device).
\ No newline at end of file |