diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index 42d770c3c..4b9ee70f5 100644 --- 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 +#### Can I integrate UID2 with Single Sign-On (SSO)? + +Yes. With popular SSO 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 index f1050b845..b5750c712 100644 --- 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) + + + ## 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 index 8fa571ae1..63e8dcf2a 100644 --- 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) + + + ## 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 index f92883633..ee9519503 100644 --- 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) + + + ## 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 index 973edeaaa..970a07fe0 100644 --- 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/) - + +## Integrating with Single Sign-On (SSO) + + ## Complete UID2 Account Setup @@ -385,4 +389,4 @@ function bytesToBase64(bytes) { const binString = Array.from(bytes, (x) => String.fromCodePoint(x)).join(""); return btoa(binString); } -``` \ No newline at end of file +``` diff --git a/docs/guides/integration-javascript.md b/docs/guides/integration-javascript.md index 9573c8dbb..4c02c2538 100644 --- 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) + + + ## 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 index 44ff7927e..532e94c14 100644 --- 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) + + + ## 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 index 0e0045b2b..370e47583 100644 --- 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) + + + ## 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 app names 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 index d27de6a17..a413cfc6b 100644 --- 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) + + + ## 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 index 8e4276683..de218ec67 100644 --- 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) + + + ## 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 index c96038669..4e2f1c0a6 100644 --- 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) + + + ## 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 index d5735cc69..be1eba220 100644 --- 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 +## Integrating with Single Sign-On (SSO) + + + ### 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 index 35119a774..289751b66 100644 --- 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) + + + ## 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 index f63889d51..7d4f218f0 100644 --- 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) + + + ## Getting Started To get started, follow these steps: diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index ad0d64d7a..f6fb08b82 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -68,6 +68,8 @@ import Link from '@docusaurus/Link'; Normalize **O** +OpenID Connect (OIDC) | +Opaque | Open Operator | Operator | Operator key | @@ -308,6 +310,10 @@ import Link from '@docusaurus/Link';
+
OpenID Connect (OIDC)
+
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.
+
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).
+
Opaque
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.
@@ -427,6 +433,9 @@ import Link from '@docusaurus/Link';
Single sign-on (SSO)
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.
+
SSO
+
See Single sign-on (SSO).
+
Subscription ID
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 Subscription ID and Public Key.
diff --git a/docs/ref-info/ref-integration-sso-providers.md b/docs/ref-info/ref-integration-sso-providers.md new file mode 100644 index 000000000..2a37d6304 --- /dev/null +++ b/docs/ref-info/ref-integration-sso-providers.md @@ -0,0 +1,105 @@ +--- +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 SSO 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 technical information about how to do this, for publisher integrations with several popular SSO providers. + +:::important +You are responsible for ensuring that your use of email addresses to create UID2s is consistent with your UID2 agreement, your company’s privacy policy, and any other platform or third-party terms to which your company is subject. +::: + + + +## 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 OpenID Connect (OIDC) 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). diff --git a/docs/snippets/_integrating-with-sso.mdx b/docs/snippets/_integrating-with-sso.mdx new file mode 100644 index 000000000..795b4d52f --- /dev/null +++ b/docs/snippets/_integrating-with-sso.mdx @@ -0,0 +1,3 @@ +If you integrate with one or more SSO 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. + +For details, see [Publisher Integration with SSO Providers](/docs/ref-info/ref-integration-sso-providers). \ No newline at end of file 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 new file mode 100644 index 000000000..e600ce1a6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-integration-sso-providers.md @@ -0,0 +1,105 @@ +--- +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 SSO 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 technical information about how to do this, for publisher integrations with several popular SSO providers. + +:::important +You are responsible for ensuring that your use of email addresses to create UID2s is consistent with your UID2 agreement, your company’s privacy policy, and any other platform or third-party terms to which your company is subject. +::: + + + +## 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 OpenID Connect (OIDC) 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). 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 new file mode 100644 index 000000000..13edab828 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_integrating-with-sso.mdx @@ -0,0 +1 @@ +For information about integrating with Single Sign-On (SSO) providers, see [Publisher Integration with SSO Providers](/docs/ref-info/ref-integration-sso-providers.md). \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index aed16af58..eaa5a89c6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -312,6 +312,7 @@ const fullSidebar = [ 'ref-info/ref-integration-approaches', 'ref-info/ref-tokens', 'ref-info/ref-server-side-token-generation', + 'ref-info/ref-integration-sso-providers', ], },