diff options
Diffstat (limited to 'chromium/docs/website/site/administrators/advanced-integration-for-saml-sso-on-chrome-devices/index.md')
| -rw-r--r-- | chromium/docs/website/site/administrators/advanced-integration-for-saml-sso-on-chrome-devices/index.md | 264 |
1 files changed, 0 insertions, 264 deletions
diff --git a/chromium/docs/website/site/administrators/advanced-integration-for-saml-sso-on-chrome-devices/index.md b/chromium/docs/website/site/administrators/advanced-integration-for-saml-sso-on-chrome-devices/index.md deleted file mode 100644 index 432489270ec..00000000000 --- a/chromium/docs/website/site/administrators/advanced-integration-for-saml-sso-on-chrome-devices/index.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -breadcrumbs: -- - /administrators - - Documentation for Administrators -page_name: advanced-integration-for-saml-sso-on-chrome-devices -title: Advanced Integration for SAML SSO on Chrome Devices ---- - -This page describes the advanced integration that **may** be done in enabling -SAML SSO on Chrome Devices. This article is intended for partners, SAML SSO -vendors and IT administrators. The integration described in this document is not -mandatory for the feature to work. For basic information on how SAML SSO can be -enabled for Chrome Devices, please refer to [this -article](https://support.google.com/chrome/a/answer/6060880). - -### Chrome Credentials Passing API - -API version 1.0 - 3rd June 2014 - -#### Motivation - -Users can sign in to Chrome with their Google accounts. The password is verified -by Google’s authentication servers but is also used locally in Chrome to provide -features such as session lock/unlock, Chrome Device offline sign-in and Chrome -Device user data encryption. For SAML users, authentication is performed by a -third-party identity provider (IdP). This document describes an API that SAML -IdPs can use to securely provide Chrome with the user credentials required to -implement the session lock/unlock, offline sign-in, and data encryption -features. - -#### Overview - -The Chrome sign-in flow is entirely web-based. Google’s authentication service -redirects to the IdP, the IdP guides the user through the authentication process -and eventually redirects back to a Google URL, reporting success or failure (see -the [Google developer -documentation](https://developers.google.com/google-apps/sso/saml_reference_implementation)). -The IdP’s authentication flow typically consists of at least three steps: - - an HTML login form collects user credentials - - the IdP verifies that the credentials submitted are correct - - an HTML page performs the redirect to the Google URL, indicating - success/failure - -This document introduces a JavaScript API via which the IdP can pass user -credentials to Chrome in step 1 and can inform Chrome when the credentials have -been verified in step 3. The API works locally: API methods are called by a -script that is executed by Chrome as part of the SAML IdP’s web-based -authentication flow and are processed by the same instance of Chrome. They do -not flow through any server. The API methods are provided by a JavaScript file -that handles the lower-level communication with Chrome. This file is hosted by -Google at: - -<https://ssl.gstatic.com/accounts/chrome/users-1.0.js> - -We recommend that SAML IdPs reference this file at the above location in their -scripts. This way, any improvements and bug fixes to the file will be picked up -automatically. We will make every effort to keep the API provided by this file -stable. - -#### Key Types - -To support session lock/unlock, offline sign-in and user data encryption, Chrome -must be able to authenticate a returning user without contacting any servers. -This is done by deriving a key from the user’s password via a one-way hash -function during initial authentication. When the user returns and enters his/her -password again, the same one-way hash function is applied to this password. If -the resulting keys match, the password entered was correct and the user is -authenticated. - -Chrome uses a built-in one-way hash function to derive keys from passwords for -non-SAML users. The same one-way hash function is used when a SAML IdP passes a -user’s password to Chrome via the API described in this document. Chrome -discards the password after hashing and does not store it anywhere. An -alternative is for the IdP to apply a one-way hash function and pass the derived -key to Chrome. When the user returns and enters his/her password, Chrome must -apply the same one-way hash function to determine whether the password entered -is correct. The IdP must therefore use a one-way hash function supported by -Chrome and must also pass Chrome any additional metadata required to repeat the -hashing, such as a salt. - -Chrome provides the SAML IdP with a list of supported key derivation mechanisms -when the IdP initializes the API. KEY_TYPE_PASSWORD_PLAIN is always supported. -For this key type, the IdP passes the password to Chrome and Chrome applies its -built-in one-way hash function to it. Additional key types, in which the IdP -applies a one-way hash function and passes the key and metadata to Chrome, will -be added in the future. - -#### API Methods - -The API consists of three JavaScript methods: - - initialize(callback) - - add(details, callback) - - complete(details, callback) - -All methods are asynchronous. Each method will invoke the callback passed to it -when its work is done. The initialize method must be called first to initialize -the API. The add method is then used to pass credentials to Chrome and the -complete method is used to inform Chrome that the passed credentials have been -verified. IdP login flows typically span multiple HTML login pages. The API -supports this by allowing its methods to be called from different pages. - -However, the API must correlate the complete call that indicates authentication -success with the add call that passed the corresponding credentials. This -correlation is established using the token argument: The SAML IdP passes a token -of its choosing in the details provided to the add call and must then pass the -same token in the details of the corresponding complete call. The API uses the -token to correlate these method calls only. The token is treated as opaque, is -not interpreted in any way and is discarded at the end of the sign-in process. - -If authentication fails, Chrome may return to the sign-in form, asking the user -to try signing in again. A sign-in process can thus encompass multiple -authentication attempts. To ensure that method calls are correlated correctly, -the SAML IdP should use a different token for each of these authentication -attempts. The IdP must then choose a token when calling add and must keep this -token as part of its internal state until complete is called. The need to -generate and keep track of a suitable token can be avoided by using the -RelayState (see the [Google SAML developer -documentation](https://developers.google.com/google-apps/sso/saml_reference_implementation) -for a definition) as the token. The RelayState meets all requirements that the -token must fulfill: - - The RelayState remains constant throughout an authentication attempt - - The RelayState is different for each authentication attempt - - The RelayState must be passed through from the start to the end of the - authentication flow so that it will be available in steps 1 and 3 of the - flow - -While the RelayState is an obvious choice for the token, a SAML IdP is free to -choose any other token instead, as long as it allows the add and complete calls -to be correlated. - -> ## initialize(callback) - -> The initialize method should be invoked once at the start of the -> authentication flow. While the API is currently implemented by Chrome only, a -> SAML IdP is not required to (and should not) interpret the user agent string -> to determine whether the API is available or not. Instead, the initialize -> method should always be called at the start of the authentication flow, -> regardless of user agent. - -> If the authentication attempt is part of a sign-in process on a version of -> Chrome that provides the API, Chrome will invoke the callback with a list of -> supported key types. Once the callback has been invoked by Chrome, the IdP may -> use the API by calling the add and complete methods. - -> In all other cases (e.g., not Chrome, older version of Chrome, not part of the -> sign-in process), the callback will not be invoked. If the callback is not -> invoked, the API is not available and the IdP must not call any of its other -> methods. If the IdP’s authentication flow spans multiple HTML pages, the IdP -> must keep track of the initialization result across these pages. If the API is -> available, the IdP should call the add and complete methods at the appropriate -> points in the authentication flow. Otherwise, the add and complete methods -> must not be called. - -> The callback should be a function that takes a single argument, keyTypes. -> Chrome passes an array of string constants indicating the supported key -> derivation mechanisms via this argument (see the key types section for -> details). The constant ’KEY_TYPE_PASSWORD_PLAIN’ will always be present in -> this array. Additional constants indicating further key derivation mechanisms -> will be added in the future. - -> ## add(details, callback) - -> This method should be invoked when the user has finished entering his/her -> credentials. The details should be a JavaScript object that contains the -> following fields: - -> token -> user -> passwordBytes -> keyType - -> The token is used to correlate the add call with a subsequent complete call. -> It is not interpreted by the API in any way and may be freely chosen by the -> IdP (see the API methods section for details). The user field should be set to -> the user’s e-mail address. If the IdP does not know the user’s e-mail address, -> an empty string should be passed. - -> The next two fields are used to pass a key to Chrome. keyType indicates the -> key derivation mechanism that the IdP used to derive the key from the user’s -> password. It must be one of the string constants that the API returned in the -> keyTypes array during initialization (see the previous section for details). -> passwordBytes contains the key and any metadata required to repeat the hashing -> process that was used to derive the key. - -> When the keyType is ’KEY_TYPE_PASSWORD_PLAIN’, passwordBytes contains the -> password itself. For other key types that will be added in the future, -> passwordBytes will contain the metadata, such as a salt, and the key, -> separated by a delimiter. - -> The callback will be invoked when Chrome has received the credentials. Since -> the user has not been authenticated yet, Chrome keeps the credentials in -> memory only and does not store them permanently until the corresponding -> complete method is called. - -> The add method will typically be called when the HTML login form is about to -> submitted. It is important to not actually submit the form until after the -> callback has been invoked. If the IdP calls the add method and submits the -> form without waiting for the callback, the HTML page containing the login form -> and any scripts it is running it will be torn down immediately, preventing the -> credentials from reaching Chrome. The recommended way to handle form -> submission is to set the callback to form.submit.bind(form), where form is the -> DOM node representing the login form. This way, the form will be submitted -> automatically when Chrome has received the credentials and invokes the -> callback. - -> If the credentials entered are incorrect, the IdP will typically end the -> authentication flow with a SAMLResponse indicating failure. However, an IdP -> may also redirect back to the IdP’s login form, allowing the user to try -> entering his/her credentials again. If the IdP implements this flow, the add -> method should be called whenever new credentials are entered. It is -> permissible to reuse the same token in this case. When the add method is -> called with new credentials, any credentials previously passed with the same -> token are superseded and replaced. - -> ## complete(details, callback) - -> The complete method should be invoked when the user’s credentials have been -> verified by the SAML IdP and the user is authenticated. The details should be -> a JavaScript object that contains one field, token. The token must match the -> one that was passed to the add call for this authentication attempt, allowing -> the two calls to be correlated. The complete call indicates that the -> credentials which the IdP had passed to the corresponding add call are valid. -> Chrome will use these credentials to provide the session lock/unlock, offline -> sign-in, and data encryption features for this user. The callback will be -> invoked when Chrome has processed the credentials and has stored them -> permanently. - -> After verifying the user’s credentials, an IdP needs to redirect to a Google -> URL, passing the RelayState and SAMLResponse. This is typically done by -> serving an HTML page that contains a hidden form which is submitted to the -> Google URL automatically upon page load. It is important to not actually -> submit the form until after the callback has been invoked. The recommended way -> to handle this is to call the complete method upon page load, setting the -> callback to form.submit.bind(form), where form is the DOM node representing -> the hidden form. This way, the form will be submitted automatically when -> Chrome has processed the credential and invokes the callback. - -> If the credentials provided are incorrect, the IdP must not call the complete -> method. When the SAML authentication flow completes with a SAMLResponse -> indicating authentication failure, Chrome will inform the user of the -> authentication failure and will allow him/her to try again, starting a new -> authentication flow. - -#### Limitations - -The API can be used to securely pass a key derived from the user’s password to -Chrome. If the user authenticates using other means (e.g., smart card, -biometrics, single-use codes) and does not have a password, the API cannot be -used as no key can be derived. Support for other authentication types is a -separate problem outside the scope of the API at this time. - -The API is available in Chrome 36 and higher. Earlier Chrome versions behave -like other user agents that do not support the API: It is safe to call the -initialize method. Since the API is not supported, the callback passed to -initialize will never be invoked.
\ No newline at end of file |