Merge pull request #791 from IABTechLab/gwh-APIDOCS-2486-sso-doc

genwhittTTD · web-flow · commit 12e246d7da26 · 2025-01-08T15:06:36.000-05:00
add new doc re SSO publisher integrations
diff --git a/docs/getting-started/gs-faqs.md b/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.
diff --git a/docs/guides/integration-ctv-guide.md b/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
 
@@ -22,6 +23,10 @@ At a high level, to integrate with UID2, you'll implement these three key steps:
 
 To determine how you'll implement these steps, choose from the [CTV Integration Options](#ctv-integration-options).
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## CTV Integration Options
 
 You can decide on the integration option that's best for you based on where you want to generate and refresh the UID2 token. There are three options, as follows:
diff --git a/docs/guides/integration-google-ss.md b/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
 
@@ -60,6 +61,10 @@ If you want to use Secure Signals with Prebid.js, you must complete both these a
 
    For details, see [ESP Configurations](https://docs.prebid.org/dev-docs/modules/userId.html#esp-configurations) in the Prebid documentation.
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Publisher Integration
 
 When an encrypted signal is cached, the secure signals feature does not execute the handler to generate a new signal. Because of this, it is necessary to clear the cache before and after data capture.
diff --git a/docs/guides/integration-javascript-client-server.md b/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
 
@@ -46,6 +47,10 @@ For integration scenarios for publishers that do not use the SDK for JavaScript,
 If you are using Google Ad Manager and want to use the secure signals feature, first follow the steps in this guide and then follow the additional steps in the [Google Ad Manager Secure Signals Integration Guide](integration-google-ss.md).
 :::
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Integration Steps 
 
 The following diagram outlines the steps required for establishing a user's UID2 token with a publisher and how the UID2 token integrates with the RTB bidstream.
diff --git a/docs/guides/integration-javascript-client-side.md b/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,10 @@ 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) -->
-  
+
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
 
 ## Complete UID2 Account Setup
 
@@ -385,4 +389,4 @@ function bytesToBase64(bytes) {
   const binString = Array.from(bytes, (x) => String.fromCodePoint(x)).join("");
   return btoa(binString);
 }
-```
+```
diff --git a/docs/guides/integration-javascript.md b/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
 
@@ -25,6 +26,10 @@ UID2 provides an SDK for JavaScript that supports the following:
 
 For additional flexibility, UID2 also provides alternative methods for some of the features and complementary products, such as a Prebid integration.
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Client-Side or Client-Server Integration
 
 The options for integrating with UID2 using the SDK for JavaScript are summarized in the following table. Choose the option that's best for you.
diff --git a/docs/guides/integration-mobile-client-server.md b/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
 
@@ -55,6 +56,10 @@ This guide provides instructions for using either of these UID2 mobile SDKs:
 
 For instructions for installing the correct SDK/version into your mobile app, see [Add the UID2 Mobile SDK to Your Mobile App](#add-the-uid2-mobile-sdk-to-your-mobile-app).
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Complete the UID2 Account Setup
 
 To set up your account, follow the steps described in [Account Setup](../getting-started/gs-account-setup.md).
diff --git a/docs/guides/integration-mobile-client-side.md b/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
 
@@ -190,6 +191,10 @@ see UID2SDKDevelopmentApp/UID2SDKDevelopmentApp/Info.plist
 
 If necessary, you can also change the default Subscription ID and public key to values assigned to you, and connect to the UID2 Production environment. For details, see [Optional: Specifying the API Base URL to Reduce Latency](#optional-specifying-the-api-base-url-to-reduce-latency).
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Complete the UID2 Account Setup
 
 To set up your account, follow the steps described in [Account Setup](../getting-started/gs-account-setup.md). As part of the account setup process, you'll need to provide a list of <Link href="../ref-info/glossary-uid#gl-app-name">app names</Link> for all the mobile apps that you'll be integrating with the UID2 mobile SDKs, including any of these values that apply:
diff --git a/docs/guides/integration-mobile-overview.md b/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
 
@@ -28,6 +29,10 @@ UID2 provides SDKs for Android/iOS that support the following:
 
 For additional flexibility, UID2 also provides alternative methods for some of the features and complementary products, such as UID2 Google GMA/IMA Plugins. Available options are described in the individual guides: see [Integration Overview: High-Level Steps](#integration-overview-high-level-steps).
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Integration Overview: High-Level Steps
 
 At a high level, to integrate your mobile app with UID2 using the UID2 mobile SDKs, you'll need to complete the following steps:
diff --git a/docs/guides/integration-prebid-client-server.md b/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
 
@@ -38,6 +39,10 @@ Information about how to integrate Prebid with UID2 is also in the following loc
 
 GWH note 12/14/23: We have client-side and server-side examples for JS SDK but only server-side for Prebid. -->
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Integration Overview: High-Level Steps
 
 You'll need to complete the following steps:
diff --git a/docs/guides/integration-prebid-client-side.md b/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
 
@@ -32,6 +33,10 @@ An example of the UID2 Prebid.js client-side integration is available at the fol
 - Code: [Example Prebid.js UID2 Integration](https://github.com/IABTechLab/uid2docs/tree/main/static/examples/cstg-prebid-example)
 - Running site: [UID2 Prebid.js Client-Side Integration Example](https://unifiedid.com/examples/cstg-prebid-example/)
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Integration Overview: High-Level Steps
 
 You'll need to complete the following steps:
diff --git a/docs/guides/integration-prebid.md b/docs/guides/integration-prebid.md
@@ -9,6 +9,7 @@ displayed_sidebar: sidebarPublishers
 ---
 
 import Link from '@docusaurus/Link';
+import IntegratingWithSSO from '/docs/snippets/_integrating-with-sso.mdx';
 import StoreUID2TokenInBrowser from '/docs/snippets/_prebid-storing-uid2-token-in-browser.mdx';
 
 # UID2 Integration Overview for Prebid
@@ -32,6 +33,10 @@ UID2 is not designed to be used where GDPR applies. The module checks the consen
 
 <!-- GDPR statement difference for UID2/EUID | UID2 is not designed to be used where GDPR applies | EUID is designed to be used only where GDPR applies. -->
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ### Generating the UID2 Token
 
 Depending on access to DII, there are two methods to generate UID2 tokens for use with Prebid.js, as shown in the following table.
diff --git a/docs/guides/integration-publisher-server-side.md b/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
 
@@ -39,6 +40,10 @@ The guide outlines the [basic steps](#integration-steps) that you need to consid
 
 See also [FAQs](#faqs).
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Integration Steps
 
 The following diagram outlines the steps required for a user to establish a UID2 token with a publisher and how the UID2 token integrates with the RTB bidstream.
diff --git a/docs/overviews/overview-publishers.md b/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
@@ -60,6 +62,10 @@ The following steps provide a high-level outline of the workflow intended for or
 
 ![Publisher Workflow](images/UID2PublisherAndSSPWorkflow.svg)
 
+## Integrating with Single Sign-On (SSO)
+
+<IntegratingWithSSO />
+
 ## Getting Started
 
 To get started, follow these steps:
diff --git a/docs/ref-info/glossary-uid.md b/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>
 
diff --git a/docs/ref-info/ref-integration-sso-providers.md b/docs/ref-info/ref-integration-sso-providers.md
diff --git a/docs/snippets/_integrating-with-sso.mdx b/docs/snippets/_integrating-with-sso.mdx
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-integration-sso-providers.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-integration-sso-providers.md
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_integrating-with-sso.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_integrating-with-sso.mdx
diff --git a/sidebars.js b/sidebars.js
