add new doc re SSO publisher integrations

docs/getting-started/gs-faqs.md

@@ -67,6 +67,7 @@ Here are some frequently asked questions for publishers using the UID2 framework
 - [How can I test the refresh token workflow?](#how-can-i-test-the-refresh-token-workflow)
 - [What is the uniqueness and rotation policy for UID2 tokens?](#what-is-the-uniqueness-and-rotation-policy-for-uid2-tokens)
 - [What does a UID2 token look like in the bidstream?](#what-does-a-uid2-token-look-like-in-the-bidstream)
+- [Can I integrate UID2 with Single Sign-On (SSO)?](#can-i-integrate-uid2-with-single-sign-on-sso)
 
 #### How can I test that the DII sent and the returned token match up?
 
@@ -147,6 +148,12 @@ There are many ways to approach UID2 implementation. Here is one example of a co
 
 <ExampleTokenInBidstream />
 
+#### Can I integrate UID2 with Single Sign-On (SSO)?
+
+Yes. With popular <a href="../ref-info/glossary-uid#gl-sso">SSO</a> integration options such as Sign in with Google, Facebook Login, Sign in with Apple, or OpenPass, you can retrieve the email address and use it to generate a UID2.
+
+For details, see [Publisher Integration with SSO Providers](/docs/ref-info/ref-integration-sso-providers.md).
+
 ## FAQs for Advertisers and Data Providers
 
 Here are some frequently asked questions for advertisers and data providers using the UID2 framework.

docs/guides/integration-ctv-guide.md

@@ -8,6 +8,7 @@ sidebar_position: 04
 ---
 
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # CTV Integration Guide
 
@@ -81,3 +82,7 @@ The following table shows supported operating systems, with links to applicable
 | :--- | :--- | :--- |
 | [Apple tvOS](https://developer.apple.com/tvos/) | [UID2 Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md) | [SDK for iOS Reference Guide](../sdks/sdk-ref-ios.md) |
 | [Android TV](https://www.android.com/tv/) | [UID2 Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md) | [SDK for Android Reference Guide](../sdks/sdk-ref-android.md) |
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />

docs/guides/integration-google-ss.md

@@ -8,6 +8,7 @@ sidebar_position: 10
 ---
 
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # Google Ad Manager Secure Signals Integration Guide
 
@@ -120,6 +121,10 @@ The following sample implementations are available to illustrate how to integrat
 
 Each sample implementation has its own instructions.
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Troubleshooting
 
 Here is some troubleshooting information that might help you in working with Google Secure Signals for your UID2 integration:

docs/guides/integration-javascript-client-server.md

@@ -9,6 +9,7 @@ sidebar_position: 02
 
 import Link from '@docusaurus/Link';
 import ExampleClientServerSendUid2ToSdk from '/docs/snippets/_example-client-server-send-uid2-to-sdk.mdx'; 
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # Client-Server Integration Guide for JavaScript
 
@@ -156,6 +157,10 @@ The client lifecycle is complete when the user decides to log out from the publi
 </script>
 ```
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## FAQs
 
 For a list of frequently asked questions for the publisher audience, see [FAQs for Publishers](../getting-started/gs-faqs.md#faqs-for-publishers).

docs/guides/integration-javascript-client-side.md

@@ -10,6 +10,7 @@ sidebar_position: 04
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # Client-Side Integration Guide for JavaScript
 
@@ -62,7 +63,6 @@ For a sample implementation, see this example:
 - Running site: [Client-Side Integration Example, UID2 JavaScript SDK](https://cstg-integ.uidapi.com/)
 
 <!-- (Source code for running site: https://github.com/IABTechLab/uid2-web-integrations) -->
-
 
 ## Complete UID2 Account Setup
 
@@ -385,4 +385,8 @@ function bytesToBase64(bytes) {
   const binString = Array.from(bytes, (x) => String.fromCodePoint(x)).join("");
   return btoa(binString);
 }
-```
+```
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />

docs/guides/integration-javascript.md

@@ -8,6 +8,7 @@ sidebar_position: 04
 ---
 
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # UID2 Integration Overview for JavaScript
 
@@ -69,3 +70,7 @@ For detailed instructions, refer to one of the following integration guides:
 
 - [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md)
 - [Client-Server Integration Guide for JavaScript](integration-javascript-client-server.md)
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />

docs/guides/integration-mobile-client-server.md

@@ -15,6 +15,7 @@ import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx';
 import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx';
 import PrebidMobileSDK from '/docs/snippets/_mobile_docs_prebid-mobile.mdx';
 import ErrorResponseStates from '/docs/snippets/_mobile-docs-error-response-states.mdx';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # UID2 Client-Server Integration Guide for Mobile
 
@@ -314,6 +315,10 @@ The UID2 integration with Prebid Mobile SDK requires version 1.6.0 of the UID2 S
 
 <PrebidMobileSDK />
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Error Response States
 
 <ErrorResponseStates />

docs/guides/integration-mobile-client-side.md

@@ -15,6 +15,7 @@ import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx';
 import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx';
 import PrebidMobileSDK from '/docs/snippets/_mobile_docs_prebid-mobile.mdx';
 import ErrorResponseStates from '/docs/snippets/_mobile-docs-error-response-states.mdx';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # UID2 Client-Side Integration Guide for Mobile
 
@@ -724,6 +725,10 @@ The UID2 integration with Prebid Mobile SDK requires version 1.6.0 of the UID2 S
 
 <PrebidMobileSDK />
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Error Response States
 
 <ErrorResponseStates />

docs/guides/integration-mobile-overview.md

@@ -9,6 +9,7 @@ displayed_sidebar: sidebarPublishers
 ---
 
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # UID2 Mobile Integration Overview for Android and iOS
 
@@ -168,3 +169,7 @@ Some error responses indicate  a networking problem resulting in your app not be
    The SDK tries to refresh the UID2 token in the background. If an error such as an IOException occurs, the SDK retries multiple times. If retry is not successful, this exception is displayed.
 
 Another good troubleshooting step is to enable logging. For details, see [Enable Logging](integration-mobile-client-side.md#enable-logging).
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />

docs/guides/integration-prebid-client-server.md

@@ -10,6 +10,7 @@ sidebar_position: 04
 import Link from '@docusaurus/Link';
 import AddPrebidjsToYourSite from '/docs/snippets/_prebid-add-prebidjs-to-your-site.mdx';
 import StoreUID2TokenInBrowser from '/docs/snippets/_prebid-storing-uid2-token-in-browser.mdx';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # UID2 Client-Server Integration Guide for Prebid.js
 
@@ -375,3 +376,7 @@ if you're using Prebid.js, and you're planning to pass UID2 tokens to Google usi
 
 - In your Google Ad Manager account, make sure that encrypted signals are properly shared with third-party bidders: see [Allow Secure Signals Sharing](integration-google-ss.md#allow-secure-signals-sharing).
 - Update your Prebid.js configuration: see [Optional: Enable Secure Signals in Prebid.js](integration-google-ss.md#optional-enable-secure-signals-in-prebidjs).
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />

docs/guides/integration-prebid-client-side.md

@@ -10,6 +10,7 @@ sidebar_position: 04
 import Link from '@docusaurus/Link';
 import AddPrebidjsToYourSite from '/docs/snippets/_prebid-add-prebidjs-to-your-site.mdx';
 import StoreUID2TokenInBrowser from '/docs/snippets/_prebid-storing-uid2-token-in-browser.mdx';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # UID2 Client-Side Integration Guide for Prebid.js
 
@@ -196,3 +197,7 @@ if you're using Prebid.js, and you're planning to pass UID2 tokens to Google usi
 
 - In your Google Ad Manager account, make sure that encrypted signals are properly shared with third-party bidders: see [Allow Secure Signals Sharing](integration-google-ss.md#allow-secure-signals-sharing).
 - Update your Prebid.js configuration: see [Optional: Enable Secure Signals in Prebid.js](integration-google-ss.md#optional-enable-secure-signals-in-prebidjs).
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />

docs/guides/integration-publisher-server-side.md

@@ -8,6 +8,7 @@ sidebar_position: 03
 ---
 
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 
 # Publisher Integration Guide, Server-Side
 
@@ -115,6 +116,10 @@ A sample implementation is available for server-side integration. See:
 - [Server-Side UID2 Integration Example (sample implementation)](https://secure-signals-srvonly-integ.uidapi.com/)
 - [Server-Side UID2 Integration Example (readme)](https://github.com/IABTechLab/uid2-examples/blob/main/publisher/server_only/README.md)
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## FAQs
 
 For a list of frequently asked questions for the publisher audience, see [FAQs for Publishers](../getting-started/gs-faqs.md#faqs-for-publishers).

docs/overviews/overview-publishers.md

@@ -9,6 +9,8 @@ banner_description: Maintain audience targeting in the ever-changing advertising
 displayed_sidebar: sidebarPublishers
 ---
 
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
+
 import Link from '@docusaurus/Link';
 
 As a publisher, you can benefit from the cross-device presence of Unified ID 2.0 (UID2) and take advantage of a consistent identity fabric on all your inventory.
@@ -34,7 +36,7 @@ The following steps provide a high-level outline of the workflow intended for or
 
 1. A user visits a publisher website, mobile app, or CTV app.
 
-1. The publisher provides transparency around its data practices and asks the user to provide an email address or phone number.
+1. The publisher provides transparency around its data practices and asks the user to provide an email address or phone number, by [SSO login](#integrating-with-single-sign-on-sso) or other means.
 
 1. Once the user has provided an email address or phone number, the publisher sends it to the UID2 Operator via an SDK or direct API integration.
    :::tip
@@ -156,6 +158,10 @@ The following resources are available for publishers integrating with Google Ad
 | IMA for Android | [UID2 IMA Plugin for Android Integration Guide](../guides/mobile-plugin-ima-android.md) | A guide that enables publishers using the Google Interactive Media Ads (IMA) SDK to include UID2 tokens in ad requests from their Android apps. |
 | IMA for iOS | [UID2 IMA Plugin for iOS Integration Guide](../guides/mobile-plugin-ima-ios.md) | A guide that enables publishers using the Google Interactive Media Ads (IMA) SDK to include UID2 tokens in ad requests from their iOS apps. |
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## FAQs for Publishers
 
 For a list of frequently asked questions for publishers using the UID2 framework, see [FAQs for Publishers](/docs/getting-started/gs-faqs.md#faqs-for-publishers).

docs/ref-info/glossary-uid.md

@@ -68,6 +68,8 @@ import Link from '@docusaurus/Link';
 <a href="#gl-normalize">Normalize</a> 
 
 **O**
+<a href="#gl-oidc">OpenID Connect (OIDC)</a> | 
+<a href="#gl-opaque">Opaque</a> | 
 <a href="#gl-open-operator">Open Operator</a> | 
 <a href="#gl-operator">Operator</a> | 
 <a href="#gl-operator-key">Operator key</a> | 
@@ -308,6 +310,10 @@ import Link from '@docusaurus/Link';
 
 <dl>
 
+<dt><MdxJumpAnchor id="gl-oidc"><a href="#gl-oidc">OpenID Connect (OIDC)</a> </MdxJumpAnchor></dt>
+<dd>OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol that allows the client to verify the identity of an end-user based on authentication by an authorization server.</dd>
+<dd>For details, see [OpenID Connect Basic Client Implementer's Guide 1.0 - draft 40](https://openid.net/specs/openid-connect-basic-1_0.html) (specification).</dd>
+
 <dt><MdxJumpAnchor id="gl-opaque"><a href="#gl-opaque">Opaque</a></MdxJumpAnchor></dt>
 <dd>When we say a UID2 token is an opaque string, we mean that the way that the token is computed, and its format, are not communicated to UID2 participants and cannot be relied upon to remain unchanged. No assumptions should be made about the format or length of the string, or any other aspect of it.</dd>
 
@@ -427,6 +433,9 @@ import Link from '@docusaurus/Link';
 <dt><MdxJumpAnchor id="gl-sso"><a href="#gl-sso">Single sign-on (SSO)</a></MdxJumpAnchor></dt>
 <dd>SSO is an acronym for Single sign-on. SSO allows a user to log in with the same credentials (usually, but not always, ID and password) to one of several software systems, such as apps or websites. SSO allows the user to log in once to multiple applications or sites using one set of credentials. With SSO, websites/apps do not have to maintain their own authentication systems.</dd>
 
+<dt><MdxJumpAnchor id="gl-sso-abbrev"><a href="#gl-sso-abbrev">SSO</a></MdxJumpAnchor></dt>
+<dd>See <a href="#gl-sso">Single sign-on (SSO)</a>.</dd>
+
 <dt><MdxJumpAnchor id="gl-subscription-id"><a href="#gl-subscription-id">Subscription ID</a></MdxJumpAnchor></dt>
 <dd>For client-side publisher integrations, the Subscription ID is one of the two values issued to publishers to uniquely identify the account. For details, see <a href="../getting-started/gs-credentials#subscription-id-and-public-key">Subscription ID and Public Key</a>.</dd>
 

docs/ref-info/ref-integration-sso-providers.md

@@ -0,0 +1,99 @@
+---
+title: Publisher Integration with SSO Providers
+sidebar_label: Publisher SSO Integration
+description: Information for publishers for using single sign-on (SSO) providers with UID2.
+hide_table_of_contents: false
+sidebar_position: 06
+---
+
+import Link from '@docusaurus/Link';
+
+# Publisher Integration with SSO Providers
+
+If you integrate with one or more <a href="glossary-uid#gl-sso">SSO</a> providers to offer SSO login, you might be able to retrieve the logged-in user's email address from the SSO provider to generate UID2 tokens.
+
+This guide provides information about how to do this, for publisher integrations with several popular SSO providers.
+
+## High-Level Steps
+
+To integrate with a single sign-on solution, the general steps are as follows:
+
+1. Get an identity token from the SSO provider.
+
+2. Extract the user's email address from the identity token.
+
+3. Pass the user's email address to the [UID2 publisher integration](../guides/summary-guides.md#publisher-integrations) of your choice.
+
+:::note
+To find out whether you have to apply [normalization and encoding](../getting-started/gs-normalization-encoding.md) to the email address, or the integration does it for you, check the documentation for your UID2 publisher integration.
+:::
+
+## Sign in with Google
+
+The following options are available for implementing [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en):
+
+- [Sign in with Google for Android](#sign-in-with-google-for-android)
+- [Sign in with Google for iOS and macOS](#sign-in-with-google-for-ios-and-macos)
+- [Sign in with Google for Web](#sign-in-with-google-for-web)
+
+### Sign in with Google for Android
+
+Follow the instructions in [Create the Sign in with Google flow](https://developer.android.com/identity/sign-in/credential-manager-siwg#create-sign). Once the token has been validated, you can retrieve the email address by using the [getEmail() method](https://cloud.google.com/java/docs/reference/google-api-client/latest/com.google.api.client.googleapis.auth.oauth2.GoogleIdToken.Payload#com_google_api_client_googleapis_auth_oauth2_GoogleIdToken_Payload_getEmail__) of the identity token payload.
+
+### Sign in with Google for iOS and macOS
+
+To get an email address from [Sign in with Google](https://developers.google.com/identity/sign-in/ios/start-integrating) on iOS or macOS, retrieve it from the `GIDGoogleUser` object. For details, see [Getting profile information](https://developers.google.com/identity/sign-in/ios/people).
+
+### Sign in with Google for Web
+
+Follow the instructions to [verify the Google ID token on your server side](https://developers.google.com/identity/gsi/web/guides/verify-google-id-token), and then retrieve the user's email address from the email field of the ID token.
+
+## Facebook Login
+
+There are two ways to integrate Facebook Login with UID2: with an <Link href="glossary-uid#gl-oidc">OpenID Connect (OIDC)</Link> token or without.
+
+### Facebook Login Using an OIDC Token on iOS
+
+To get an email address from [Facebook Login](https://developers.facebook.com/docs/facebook-login/) using an [OIDC token](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-oidc/) on iOS:
+
+1. Implement Facebook Login (for details, see [Use Facebook Login in Your iOS App](https://developers.facebook.com/docs/ios/use-facebook-login)) and request the `email` permission.
+
+1. Extract the user's email address from the OIDC authentication token: for example, by using the `Profile` helper class. For details, see [OIDC Tokens in Facebook Login for iOS](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-oidc).
+
+### Facebook Login Without an OIDC Token
+
+To get an email address from [Facebook Login](https://developers.facebook.com/docs/facebook-login/) without using an OIDC token:
+
+1. Request a [user access token](https://developers.facebook.com/docs/facebook-login/guides/access-tokens#usertokens), specifying the `email` permission.
+
+1. If the user has granted the `email` permission, make a Graph API call to the [`/me` endpoint](https://developers.facebook.com/docs/graph-api/overview#me), using the user access token, and specify `email` as one of the fields.
+
+### Sample Applications
+
+The following applications demonstrate how to integrate with Facebook Login:
+
+- [Facebook Login sample application for Android](https://github.com/facebook/facebook-android-sdk/tree/main/samples/FBLoginSample)
+
+- [Facebook Login sample application for iOS](https://github.com/facebook/facebook-ios-sdk/tree/main/samples/FacebookLoginSample)
+
+## Sign In with Apple
+
+The instructions for signing in with Apple are different for apps and websites.
+
+### Sign In with Apple in an App
+
+Request authorization, making sure to request the `email` scope. For details, see [Request Authorization with Apple ID](https://developer.apple.com/documentation/sign_in_with_apple/implementing_user_authentication_with_sign_in_with_apple#3546458).
+
+If authentication succeeds, retrieve the user's email address from the `email` property of the `ASAuthorizationAppleIDCredential` object.
+
+### Sign In with Apple JS on a Webpage
+
+Refer to the section [Handle the Authorization Response](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/configuring_your_webpage_for_sign_in_with_apple#3331292) of the page [Configure your webpage for Sign in with Apple](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/configuring_your_webpage_for_sign_in_with_apple).
+
+## Sign In with OpenPass
+
+To get an email address from an [OpenPass](https://openpass.thetradedesk.com/en) integration:
+
+1. Use the [OpenPass API](https://partner.thetradedesk.com/v3/portal/openpass/doc/OpenPassQuickstartsServerSide) or one of the [OpenPass SDKs](https://partner.thetradedesk.com/v3/portal/openpass/doc/OpenPassSDKs) to get an identity token.
+
+1. Extract the user's email address from the `email` claim of the identity token. For details, see [OpenPass Authentication Tokens](https://partner.thetradedesk.com/v3/portal/openpass/doc/OpenPassTokensAuth).