diff --git a/docs/integrations/social/facebook/README.mdx b/docs/integrations/social/facebook/README.mdx index 705acc6f4ed..20aa7bdb06a 100644 --- a/docs/integrations/social/facebook/README.mdx +++ b/docs/integrations/social/facebook/README.mdx @@ -16,7 +16,7 @@ Integrate Facebook OAuth 2.0 authentication system to enable Sign-in with Facebo -## Get started +## Get started \{#get-started} The Facebook connector enables OAuth 2.0 integration to let your application: @@ -32,18 +32,18 @@ To set up these authentication features, create a Facebook connector in Logto fi -## Utilize the Facebook connector +## Utilize the Facebook connector \{#utilize-the-facebook-connector} Once you've created a Facebook connector and connected it to Facebook, you can incorporate it into your end-user flows. Choose the options that match your needs: -### Enable "Sign-in with Facebook" +### Enable "Sign-in with Facebook" \{#enable-sign-in-with-facebook} 1. In Logto Console, go to Sign-in experience > Sign-up and sign-in 2. Add the Facebook connector under **Social sign-in** section to let users authenticate with Facebook Learn more about [social sign-in experience](/end-user-flows/sign-up-and-sign-in/social-sign-in). -### Link or unlink a Facebook account +### Link or unlink a Facebook account \{#link-or-unlink-a-facebook-account} Use the Account API to build a custom Account Center in your app that lets signed-in users link or unlink their Facebook account. [Follow the Account API tutorial](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) @@ -51,11 +51,11 @@ Use the Account API to build a custom Account Center in your app that lets signe It's allowed to enable the Facebook connector only for account linking and API access, without enabling it for social sign-in. ::: -### Access Facebook API and perform actions +### Access Facebook API and perform actions \{#access-facebook-api-and-perform-actions} Your application can retrieve stored Facebook access tokens from the Secret Vault to call Facebook APIs and automate backend tasks (for example, publishing content or managing posts). Refer to the guide on retrieving stored tokens for API access. -## Manage user's Facebook identity +## Manage user's Facebook identity \{#manage-user-s-facebook-identity} After a user links their Facebook account, admins can manage that connection in the Logto Console: @@ -67,7 +67,7 @@ After a user links their Facebook account, admins can manage that connection in Facebook's access token response does not include the specific scope information, so Logto cannot directly display the list of permissions granted by the user. However, as long as the user has consented to the requested scopes during authorization, your application will have the corresponding permissions when accessing the Facebook API. It is recommended to accurately configure the required scopes in both the Facebook Developer Console and Logto to ensure your app has the necessary access. ::: -## Reference +## Reference \{#reference} Facebook for Developers - Documentation diff --git a/docs/integrations/social/facebook/_integration.mdx b/docs/integrations/social/facebook/_integration.mdx index a5ec9d3eeec..f666cb688d4 100644 --- a/docs/integrations/social/facebook/_integration.mdx +++ b/docs/integrations/social/facebook/_integration.mdx @@ -1,4 +1,4 @@ -## Step 1: Set up an app on Facebook App Dashboard +## Step 1: Set up an app on Facebook App Dashboard \{#step-1-set-up-an-app-on-facebook-app-dashboard} Before you can use Facebook as an authentication provider, you must set up an app on the Facebook developer platform to obtain OAuth 2.0 credentials. @@ -14,7 +14,7 @@ A use case is the primary way your app will interact with Meta and determines wh 5. Fill in the **Valid OAuth Redirect URIs** with the Logto **Callback URI** (copy this from your Logto Facebook connector). After users sign in with Facebook, they'll be redirected here with an authorization code that Logto uses to finish authentication. 6. Navigate to **Use cases** and click **Customize** of your use case to add the scopes. We recommend adding `email` and `public_profile` which are required to implement Sign-in with Facebook in Logto. -## Step 2: Set up Logto connector with client credentials +## Step 2: Set up Logto connector with client credentials \{#step-2-set-up-logto-connector-with-client-credentials} 1. In the Facebook App Dashboard, click the sidebar **App settings > Basic**. 2. You will see the **App ID** and **App secret** on the panel. @@ -24,18 +24,18 @@ A use case is the primary way your app will interact with Meta and determines wh - Fill the `clientSecret` field with the **App secret**. - Click **Save and Done** in Logto to connect your identity system with Facebook. -## Step 3: Configure scopes +## Step 3: Configure scopes \{#step-3-configure-scopes} Scopes define the permissions your app requests from users and control which private data your project can access from their Facebook accounts. -### Configure scopes in Facebook App Dashboard +### Configure scopes in Facebook App Dashboard \{#configure-scopes-in-facebook-app-dashboard} 1. Navigate to **Facebook App Dashboard > Use cases** and click the **Customize** button. 2. Add only the scopes your app needs. Users will review and authorize these permissions on the Facebook consent screen: - **For authentication (Required)**: `email` and `public_profile`. - **For API access (Optional)**: Any additional scopes your app needs (e.g., `threads_content_publish`, `threads_read_replies` for accessing the Threads API). Browse the [Meta Developer Documentation](https://developers.facebook.com/docs/) for available services. -### Configure scopes in Logto +### Configure scopes in Logto \{#configure-scopes-in-logto} Choose one or more of the following approaches based on your needs: @@ -60,18 +60,18 @@ By following these steps, your Logto Facebook connector requests exactly the per If your app requests these scopes to access the Facebook API and perform actions, make sure to enable **Store tokens for persistent API access** in Logto Facebook connector. See the next section for details. ::: -## Step 4: General settings +## Step 4: General settings \{#step-4-general-settings} Here are some general settings that won't block the connection to Facebook but may affect the end-user authentication experience. -### Sync profile information +### Sync profile information \{#sync-profile-information} In the Facebook connector, you can set the policy for syncing profile information, such as user names and avatars. Choose from: - **Only sync at sign-up**: Profile info is fetched once when the user first signs in. - **Always sync at sign-in**: Profile info is updated every time the user signs in. -### Store tokens to access Facebook APIs (Optional) +### Store tokens to access Facebook APIs (Optional) \{#store-tokens-to-access-facebook-apis-optional} If you want to access Facebook APIs and perform actions with user authorization (whether via social sign-in or account linking), Logto needs to get specific API scopes and store tokens. @@ -82,7 +82,7 @@ If you want to access Facebook APIs and perform actions with user authorization Facebook doesn't provide refresh tokens. However, when token storage is enabled, Logto automatically requests a long-lived access token (60 days) upon user authentication. During this period, users can manually revoke access tokens, but otherwise won't need re-authorization to access Facebook APIs. Note: Don't add `offline_access` to the `Scope` field as this may cause errors. ::: -## Step 5: Test sign-in with Facebook's test users (Optional) +## Step 5: Test sign-in with Facebook's test users (Optional) \{#step-5-test-sign-in-with-facebook-s-test-users-optional} You can use test, developer, and admin user accounts to test sign-in with the app. You can also publish the app directly so that any Facebook user can sign in. @@ -90,7 +90,7 @@ You can use test, developer, and admin user accounts to test sign-in with the ap 2. Click the **Create test users** button to create a testing user. 3. Click the **Options** button of an existing test user to see more operations, such as "Change name and password". -## Step 6: Publish Facebook sign-in settings +## Step 6: Publish Facebook sign-in settings \{#step-6-publish-facebook-sign-in-settings} Usually, only test, admin, and developer users can sign in with the app. To enable normal Facebook users to sign in with the app in the production environment, you may need to publish this app. diff --git a/docs/integrations/social/github/README.mdx b/docs/integrations/social/github/README.mdx index b7fff0cbdd7..e66cdaa7d27 100644 --- a/docs/integrations/social/github/README.mdx +++ b/docs/integrations/social/github/README.mdx @@ -17,7 +17,7 @@ Integrate GitHub OAuth app to enable Sign-in with GitHub, account linking, and s -## Get started +## Get started \{#get-started} The GitHub connector enables OAuth 2.0 integration to let your application: @@ -33,18 +33,18 @@ To set up these authentication features, create a GitHub connector in Logto firs -## Utilize the GitHub connector +## Utilize the GitHub connector \{#utilize-the-github-connector} Once you've created a GitHub connector and connected it to GitHub, you can incorporate it into your end-user flows. Choose the options that match your needs: -### Enable "Sign-in with GitHub" +### Enable "Sign-in with GitHub" \{#enable-sign-in-with-github} 1. In Logto Console, go to Sign-in experience > Sign-up and sign-in. 2. Add the GitHub connector under **Social sign-in** section to let users authenticate with GitHub. Learn more about [social sign-in experience](/end-user-flows/sign-up-and-sign-in/social-sign-in). -### Link or unlink a GitHub account +### Link or unlink a GitHub account \{#link-or-unlink-a-github-account} Use the Account API to build a custom Account Center in your app that lets signed-in users link or unlink their GitHub account. [Follow the Account API tutorial](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) @@ -52,11 +52,11 @@ Use the Account API to build a custom Account Center in your app that lets signe It's allowed to enable the GitHub connector only for account linking and API access, without enabling it for social sign-in. ::: -### Access GitHub APIs and perform actions +### Access GitHub APIs and perform actions \{#access-github-apis-and-perform-actions} Your application can retrieve stored GitHub access tokens from the Secret Vault to call GitHub APIs and automate backend tasks (for example, creating issues, managing repositories, or automating workflows). Refer to the guide on retrieving stored tokens for API access. -## Manage user's GitHub identity +## Manage user's GitHub identity \{#manage-user-s-github-identity} After a user links their GitHub account, admins can manage that connection in the Logto Console: diff --git a/docs/integrations/social/github/_integration.mdx b/docs/integrations/social/github/_integration.mdx index de0ac74ed78..cba6632416d 100644 --- a/docs/integrations/social/github/_integration.mdx +++ b/docs/integrations/social/github/_integration.mdx @@ -1,4 +1,4 @@ -## Step 1: Create an OAuth app on GitHub +## Step 1: Create an OAuth app on GitHub \{#step-1-create-an-oauth-app-on-github} Before you can use GitHub as an authentication provider, you must create an OAuth App on GitHub to obtain OAuth 2.0 credentials. @@ -17,7 +17,7 @@ We suggest not checking the box for **Enable Device Flow**, as users who sign in For more details on setting up GitHub OAuth Apps, see [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). ::: -## Step 2: Configure your Logto connector +## Step 2: Configure your Logto connector \{#step-2-configure-your-logto-connector} After creating the OAuth app in GitHub, you'll be redirected to a details page where you can copy the Client ID and generate a Client secret. @@ -29,18 +29,18 @@ After creating the OAuth app in GitHub, you'll be redirected to a details page w Keep your Client secret secure and never expose it in client-side code. GitHub client secrets cannot be recovered if lost - you'll need to generate a new one. ::: -## Step 3: Configure scopes (Optional) +## Step 3: Configure scopes (Optional) \{#step-3-configure-scopes-optional} Scopes define the permissions your app requests from users and control which data your app can access from their GitHub accounts. Use the `Scopes` field in Logto to request extra permissions from GitHub. Choose one of the following approaches based on your needs: -### Option 1: No extra API scopes needed +### Option 1: No extra API scopes needed \{#option-1-no-extra-api-scopes-needed} - Leave the `Scopes` field in your Logto GitHub connector blank. - The default scope `read:user` will be requested to ensure Logto can get basic user info (e.g., email, name, avatar) properly. -### Option 2: Request additional scopes at sign-in +### Option 2: Request additional scopes at sign-in \{#option-2-request-additional-scopes-at-sign-in} - Browse all available [GitHub scopes for OAuth apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) and add only the scopes your app needs. - Enter all desired scopes in the **Scopes** field, separated by spaces. @@ -52,7 +52,7 @@ Use the `Scopes` field in Logto to request extra permissions from GitHub. Choose - `notifications`: Access to notifications - Ensure all scopes are spelled correctly and valid. An incorrect or unsupported scope will result in an "Invalid scope" error from GitHub. -### Option 3: Request incremental scopes later +### Option 3: Request incremental scopes later \{#option-3-request-incremental-scopes-later} - After the user signs in, you can request additional scopes on demand by reinitiating a federated social authorization flow and updating users' stored token set. - These additional scopes do not need to be filled in the `Scopes` field in your Logto GitHub connector, and can be achieved through Logto's Social Verification API. @@ -63,18 +63,18 @@ By following these steps, your Logto GitHub connector requests exactly the permi If your app requests these scopes to access the GitHub API and perform actions, make sure to enable **Store tokens for persistent API access** in Logto GitHub connector. See the next section for details. ::: -## Step 4: General settings +## Step 4: General settings \{#step-4-general-settings} Here are some general settings that won't block the connection to GitHub but may affect the end-user authentication experience. -### Sync profile information +### Sync profile information \{#sync-profile-information} In the GitHub connector, you can set the policy for syncing profile information, such as user names and avatars. Choose from: - **Only sync at sign-up**: Profile info is fetched once when the user first signs in. - **Always sync at sign-in**: Profile info is updated every time the user signs in. -### Store tokens to access GitHub APIs (Optional) +### Store tokens to access GitHub APIs (Optional) \{#store-tokens-to-access-github-apis-optional} If you want to access GitHub APIs and perform actions with user authorization (whether via social sign-in or account linking), Logto needs to get specific API scopes and store tokens. @@ -87,7 +87,7 @@ When using a GitHub **OAuth App** as described in this tutorial, you cannot get If you want the access token to expire or use refresh tokens, consider integrating with a **GitHub App** instead. Learn about the [differences between GitHub Apps and OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). ::: -## Step 5: Test your integration (Optional) +## Step 5: Test your integration (Optional) \{#step-5-test-your-integration-optional} Before going live, test your GitHub integration: diff --git a/docs/integrations/social/google/README.mdx b/docs/integrations/social/google/README.mdx index e3ed49d3832..08fd7b77799 100644 --- a/docs/integrations/social/google/README.mdx +++ b/docs/integrations/social/google/README.mdx @@ -16,7 +16,7 @@ Integrate Google OAuth 2.0 authentication system to enable Sign-in with Google, -## Get started +## Get started \{#get-started} The Google connector enables OAuth 2.0 integration to let your application: @@ -32,11 +32,11 @@ To set up these authentication features, create a Google connector in Logto firs -## Utilize the Google connector +## Utilize the Google connector \{#utilize-the-google-connector} Once you've created a Google connector and connected it to Google, you can incorporate it into your end-user flows. Choose the options that match your needs: -### Enable "Sign-in with Google" +### Enable "Sign-in with Google" \{#enable-sign-in-with-google} 1. In Logto Console, go to Sign-in experience > Sign-up and sign-in. 2. Add the Google connector under **Social sign-in** section to let users authenticate with Google. @@ -44,7 +44,7 @@ Once you've created a Google connector and connected it to Google, you can incor Learn more about [social sign-in experience](/end-user-flows/sign-up-and-sign-in/social-sign-in). -### Link or unlink a Google account +### Link or unlink a Google account \{#link-or-unlink-a-google-account} Use the Account API to build a custom Account Center in your app that lets signed-in users link or unlink their Google account. [Follow the Account API tutorial](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) @@ -52,11 +52,11 @@ Use the Account API to build a custom Account Center in your app that lets signe It's allowed to enable the Google connector only for account linking and API access, without enabling it for social sign-in. ::: -### Access Google APIs and perform actions +### Access Google APIs and perform actions \{#access-google-apis-and-perform-actions} Your application can retrieve stored Google access tokens from the Secret Vault to call Google APIs and automate backend tasks (for example, managing Google Drive files, creating Calendar events, or sending emails through Gmail). Refer to the guide on retrieving stored tokens for API access. -## Manage user's Google identity +## Manage user's Google identity \{#manage-user-s-google-identity} After a user links their Google account, admins can manage that connection in the Logto Console: diff --git a/docs/integrations/social/google/_integration.mdx b/docs/integrations/social/google/_integration.mdx index 9be9ab3cfdc..ffbd2f5de63 100644 --- a/docs/integrations/social/google/_integration.mdx +++ b/docs/integrations/social/google/_integration.mdx @@ -1,4 +1,4 @@ -## Step 1: Create a project on Google Auth Platform +## Step 1: Create a project on Google Auth Platform \{#step-1-create-a-project-on-google-auth-platform} Before you can use Google as an authentication provider, you must set up a project in the Google Cloud Console to obtain OAuth 2.0 credentials. If you already have a project, you can skip this step. @@ -17,7 +17,7 @@ Before you can use Google as an authentication provider, you must set up a proje If you choose **External** audience type, you'll need to add test users during development and publish your app for production use. ::: -## Step 2: Create OAuth 2.0 credentials +## Step 2: Create OAuth 2.0 credentials \{#step-2-create-oauth-2-0-credentials} Navigate to the [Credentials](https://console.cloud.google.com/apis/credentials) page in Google Cloud Console and create OAuth credentials for your application. @@ -29,7 +29,7 @@ Navigate to the [Credentials](https://console.cloud.google.com/apis/credentials) - **Authorized redirect URIs**: Add the Logto **Callback URI** (copy this from your Logto Google connector) 5. Click **Create** to generate the OAuth client. -## Step 3: Configure Logto connector with credentials +## Step 3: Configure Logto connector with credentials \{#step-3-configure-logto-connector-with-credentials} After creating the OAuth client, Google will display a modal with your credentials: @@ -41,11 +41,11 @@ After creating the OAuth client, Google will display a modal with your credentia Keep your client secret secure and never expose it in client-side code. If compromised, generate a new one immediately. ::: -## Step 4: Configure scopes +## Step 4: Configure scopes \{#step-4-configure-scopes} Scopes define the permissions your app requests from users and control which data your app can access from their Google accounts. -### Configure scopes in Google Cloud Console +### Configure scopes in Google Cloud Console \{#configure-scopes-in-google-cloud-console} 1. Navigate to **APIs & Services > OAuth consent screen > Scopes**. 2. Click **Add or Remove Scopes** and select only the scopes your app requires: @@ -57,7 +57,7 @@ Scopes define the permissions your app requests from users and control which dat 3. Click **Update** to confirm the selection. 4. Click **Save and Continue** to apply the changes. -### Configure scopes in Logto +### Configure scopes in Logto \{#configure-scopes-in-logto} Choose one or more of the following approaches based on your needs: @@ -83,7 +83,7 @@ By following these steps, your Logto Google connector requests exactly the permi If your app requests these scopes to access the Google API and perform actions, make sure to enable **Store tokens for persistent API access** in Logto Google connector. See the next section for details. ::: -## Step 5: Customize authentication prompts +## Step 5: Customize authentication prompts \{#step-5-customize-authentication-prompts} Configure **Prompts** in Logto to control the user authentication experience. Prompts is an array of strings that specifies the type of user interaction required: @@ -91,18 +91,18 @@ Configure **Prompts** in Logto to control the user authentication experience. Pr - `consent` - The authorization server prompts the user for consent before returning information to the client. Required to enable **offline access** for Google API access. - `select_account` - The authorization server prompts the user to select a user account. This allows users with multiple Google accounts to choose which account to use for authentication. -## Step 6: General settings +## Step 6: General settings \{#step-6-general-settings} Here are some general settings that won't block the connection to Google but may affect the end-user authentication experience. -### Sync profile information +### Sync profile information \{#sync-profile-information} In the Google connector, you can set the policy for syncing profile information, such as user names and avatars. Choose from: - **Only sync at sign-up**: Profile info is fetched once when the user first signs in. - **Always sync at sign-in**: Profile info is updated every time the user signs in. -### Store tokens to access Google APIs (Optional) +### Store tokens to access Google APIs (Optional) \{#store-tokens-to-access-google-apis-optional} If you want to access [Google APIs](https://console.cloud.google.com/apis/library) and perform actions with user authorization (whether via social sign-in or account linking), Logto needs to get specific API scopes and store tokens. @@ -116,13 +116,13 @@ If you want to access [Google APIs](https://console.cloud.google.com/apis/librar You do not need to add `offline_access` in the Logto `Scope` field — doing so may cause an error. Google uses `access_type=offline` automatically when offline access is enabled. ::: -## Step 7: Enable Google One Tap (Optional) +## Step 7: Enable Google One Tap (Optional) \{#step-7-enable-google-one-tap-optional} [Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) is a secure and streamlined way to let users sign in to your website with their Google account using a popup interface. Once you have the Google connector set up, you'll see a card for Google One Tap in the connector details page. Enable Google One Tap by toggling the switch. -### Google One Tap configuration options +### Google One Tap configuration options \{#google-one-tap-configuration-options} - **Auto-select credential if possible** - Automatically sign in the user with the Google account if [certain conditions are met](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) - **Cancel the prompt if user clicks/taps outside** - Close the Google One Tap prompt if the user clicks or taps outside the prompt. If disabled, the user must click the close button to dismiss the prompt. @@ -132,7 +132,7 @@ Once you have the Google connector set up, you'll see a card for Google One Tap Make sure to add your domain to the **Authorized JavaScript origins** section in your OAuth client configuration. Otherwise, Google One Tap cannot be displayed. ::: -### Important limitations with Google One Tap +### Important limitations with Google One Tap \{#important-limitations-with-google-one-tap} If you enable **Store tokens for persistent API access** along with **Google One Tap**, you won't automatically receive an access token or the requested scopes. @@ -142,13 +142,13 @@ To access Google APIs with Google One Tap users, you can use Logto's Social Veri Learn more about [Google One Tap limitations](https://developers.google.com/identity/gsi/web/guides/overview) in the official documentation. -## Step 8: Test and publish your app +## Step 8: Test and publish your app \{#step-8-test-and-publish-your-app} -### For Internal apps +### For Internal apps \{#for-internal-apps} If your **Audience** type in Google is set to **Internal**, your app will be available only to Google Workspace users within your organization. You can test using any account from your organization. -### For External apps +### For External apps \{#for-external-apps} If your **Audience** type is **External**: diff --git a/docs/integrations/social/oauth2/_integration.mdx b/docs/integrations/social/oauth2/_integration.mdx index 6d2ac290a1d..d0dc859c8ff 100644 --- a/docs/integrations/social/oauth2/_integration.mdx +++ b/docs/integrations/social/oauth2/_integration.mdx @@ -70,26 +70,26 @@ Each social identity provider could have their own variant on OAuth standard pro | email | string | false | email | | phone | string | false | phone | -## General settings +## General settings \{#general-settings} Here are some general settings that won't block the connection to your identity provider but may affect the end-user authentication experience. -### Social button name and logo +### Social button name and logo \{#social-button-name-and-logo} If you want to display a social button on your login page, you can set the **name** and **logo** (dark mode and light mode) of the social identity provider. This will help users recognize the social login option. -### Identity provider name +### Identity provider name \{#identity-provider-name} Each social connector has a unique Identity Provider (IdP) name to differentiate user identities. While common connectors use a fixed IdP name, custom connectors require a unique value. Learn more about [IdP names](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) for more details. -### Sync profile information +### Sync profile information \{#sync-profile-information} In the OAuth connector, you can set the policy for syncing profile information, such as user names and avatars. Choose from: - **Only sync at sign-up**: Profile info is fetched once when the user first signs in. - **Always sync at sign-in**: Profile info is updated every time the user signs in. -### Store tokens to access third-party APIs (Optional) +### Store tokens to access third-party APIs (Optional) \{#store-tokens-to-access-third-party-apis-optional} If you want to access the Identity Provider's APIs and perform actions with user authorization (whether via social sign-in or account linking), Logto needs to get specific API scopes and store tokens. @@ -101,18 +101,18 @@ If you want to access the Identity Provider's APIs and perform actions with user Keep your client secret secure and never expose it in client-side code. If compromised, generate a new one immediately in your identity provider's app settings. ::: -## Utilize the OAuth connector +## Utilize the OAuth connector \{#utilize-the-oauth-connector} Once you've created an OAuth connector and connected it to your identity provider, you can incorporate it into your end-user flows. Choose the options that match your needs: -### Enable social sign-in button +### Enable social sign-in button \{#enable-social-sign-in-button} 1. In Logto Console, go to Sign-in experience > Sign-up and sign-in. 2. Add the OAuth connector under **Social sign-in** section to let users authenticate with your identity provider. Learn more about [social sign-in experience](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). -### Link or unlink a social account +### Link or unlink a social account \{#link-or-unlink-a-social-account} Use the Account API to build a custom Account Center in your app that lets signed-in users link or unlink their social accounts. [Follow the Account API tutorial](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) @@ -120,11 +120,11 @@ Use the Account API to build a custom Account Center in your app that lets signe It's allowed to enable the OAuth connector only for account linking and API access, without enabling it for social sign-in. ::: -### Access identity provider APIs and perform actions +### Access identity provider APIs and perform actions \{#access-identity-provider-apis-and-perform-actions} Your application can retrieve stored access tokens from the Secret Vault to call your identity provider's APIs and automate backend tasks. The specific capabilities depend on your identity provider and the scopes you've requested. Refer to the guide on retrieving stored tokens for API access. -## Manage user's social identity +## Manage user's social identity \{#manage-user-s-social-identity} After a user links their social account, admins can manage that connection in the Logto Console: diff --git a/docs/integrations/social/oidc/_integration.mdx b/docs/integrations/social/oidc/_integration.mdx index 0292ebce766..7fe49c257fd 100644 --- a/docs/integrations/social/oidc/_integration.mdx +++ b/docs/integrations/social/oidc/_integration.mdx @@ -84,26 +84,26 @@ Each social identity provider could have their own variant on OIDC standard prot See [here](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) to find more details about `IdTokenVerificationConfig`. -## General settings +## General settings \{#general-settings} Here are some general settings that won't block the connection to your identity provider but may affect the end-user authentication experience. -### Social button name and logo +### Social button name and logo \{#social-button-name-and-logo} If you want to display a social button on your login page, you can set the **name** and **logo** (dark mode and light mode) of the social identity provider. This will help users recognize the social login option. -### Identity provider name +### Identity provider name \{#identity-provider-name} Each social connector has a unique Identity Provider (IdP) name to differentiate user identities. While common connectors use a fixed IdP name, custom connectors require a unique value. Learn more about [IdP names](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) for more details. -### Sync profile information +### Sync profile information \{#sync-profile-information} In the OIDC connector, you can set the policy for syncing profile information, such as user names and avatars. Choose from: - **Only sync at sign-up**: Profile info is fetched once when the user first signs in. - **Always sync at sign-in**: Profile info is updated every time the user signs in. -### Store tokens to access third-party APIs (Optional) +### Store tokens to access third-party APIs (Optional) \{#store-tokens-to-access-third-party-apis-optional} If you want to access the Identity Provider's APIs and perform actions with user authorization (whether via social sign-in or account linking), Logto needs to get specific API scopes and store tokens. @@ -115,18 +115,18 @@ If you want to access the Identity Provider's APIs and perform actions with user Keep your client secret secure and never expose it in client-side code. If compromised, generate a new one immediately in your identity provider's app settings. ::: -## Utilize the OIDC connector +## Utilize the OIDC connector \{#utilize-the-oidc-connector} Once you've created an OIDC connector and connected it to your identity provider, you can incorporate it into your end-user flows. Choose the options that match your needs: -### Enable social sign-in button +### Enable social sign-in button \{#enable-social-sign-in-button} 1. In Logto Console, go to Sign-in experience > Sign-up and sign-in. 2. Add the OIDC connector under **Social sign-in** section to let users authenticate with your identity provider. Learn more about [social sign-in experience](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). -### Link or unlink a social account +### Link or unlink a social account \{#link-or-unlink-a-social-account} Use the Account API to build a custom Account Center in your app that lets signed-in users link or unlink their social accounts. [Follow the Account API tutorial](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) @@ -134,11 +134,11 @@ Use the Account API to build a custom Account Center in your app that lets signe It's allowed to enable the OIDC connector only for account linking and API access, without enabling it for social sign-in. ::: -### Access identity provider APIs and perform actions +### Access identity provider APIs and perform actions \{#access-identity-provider-apis-and-perform-actions} Your application can retrieve stored access tokens from the Secret Vault to call your identity provider's APIs and automate backend tasks. The specific capabilities depend on your identity provider and the scopes you've requested. Refer to the guide on retrieving stored tokens for API access. -## Manage user's social identity +## Manage user's social identity \{#manage-user-s-social-identity} After a user links their social account, admins can manage that connection in the Logto Console: diff --git a/docs/integrations/sso/google-workspace/README.mdx b/docs/integrations/sso/google-workspace/README.mdx index c3c59e29750..27f3a26220c 100644 --- a/docs/integrations/sso/google-workspace/README.mdx +++ b/docs/integrations/sso/google-workspace/README.mdx @@ -44,10 +44,10 @@ With minimal configuration efforts, this connector allows integration with Micro -## Step 6: Store tokens to access Google APIs (Optional) +## Step 6: Store tokens to access Google APIs (Optional) \{#step-6-store-tokens-to-access-google-apis-optional} -## Step 7: Set email domains and enable the SSO connector +## Step 7: Set email domains and enable the SSO connector \{#step-7-set-email-domains-and-enable-the-sso-connector} diff --git a/docs/integrations/sso/google-workspace/_integration.mdx b/docs/integrations/sso/google-workspace/_integration.mdx index 9cd1588cfbd..9e2e6bdea4c 100644 --- a/docs/integrations/sso/google-workspace/_integration.mdx +++ b/docs/integrations/sso/google-workspace/_integration.mdx @@ -26,10 +26,10 @@ import Step7 from './_step-7.mdx'; -### Step 6: Store tokens to access Google APIs (Optional) +### Step 6: Store tokens to access Google APIs (Optional) \{#step-6-store-tokens-to-access-google-apis-optional} -### Step 7: Set email domains and enable the SSO connector +### Step 7: Set email domains and enable the SSO connector \{#step-7-set-email-domains-and-enable-the-sso-connector} diff --git a/docs/integrations/sso/oidc/README.mdx b/docs/integrations/sso/oidc/README.mdx index de8d2effe24..327528fc4a3 100644 --- a/docs/integrations/sso/oidc/README.mdx +++ b/docs/integrations/sso/oidc/README.mdx @@ -30,14 +30,14 @@ With minimal configuration efforts, this connector allows integration with any O -## Step 3: Configure scopes (Optional) +## Step 3: Configure scopes (Optional) \{#step-3-configure-scopes-optional} -## Step 4: Store tokens to access third-party APIs (Optional) +## Step 4: Store tokens to access third-party APIs (Optional) \{#step-4-store-tokens-to-access-third-party-apis-optional} -## Step 5: Set email domains and enable the SSO connector +## Step 5: Set email domains and enable the SSO connector \{#step-5-set-email-domains-and-enable-the-sso-connector} diff --git a/docs/integrations/sso/oidc/_integration.mdx b/docs/integrations/sso/oidc/_integration.mdx index 4b449fb465b..07cc2295488 100644 --- a/docs/integrations/sso/oidc/_integration.mdx +++ b/docs/integrations/sso/oidc/_integration.mdx @@ -12,14 +12,14 @@ import Step5 from './_step-5.mdx'; -## Step 3: Configure scopes (Optional) +## Step 3: Configure scopes (Optional) \{#step-3-configure-scopes-optional} -## Step 4: Store tokens to access third-party APIs (Optional) +## Step 4: Store tokens to access third-party APIs (Optional) \{#step-4-store-tokens-to-access-third-party-apis-optional} -## Step 5: Set email domains and enable the SSO connector +## Step 5: Set email domains and enable the SSO connector \{#step-5-set-email-domains-and-enable-the-sso-connector} diff --git a/docs/secret-vault/README.mdx b/docs/secret-vault/README.mdx index b60834456d5..9480e5a40d9 100644 --- a/docs/secret-vault/README.mdx +++ b/docs/secret-vault/README.mdx @@ -4,7 +4,7 @@ import Connectors from '@site/src/assets/connectors.svg'; The Secret Vault in Logto is designed to securely store sensitive user data—such as access tokens, API keys, passcodes, or any other confidential information that requires protection. These secrets are often used to access third-party services on behalf of the user, making secure storage essential. -## Encryption scheme +## Encryption scheme \{#encryption-scheme} To protect sensitive data, the Secret Vault employs a robust encryption scheme based on **Data Encryption Keys (DEK)** and **Key Encryption Keys (KEK)**. @@ -15,7 +15,7 @@ To protect sensitive data, the Secret Vault employs a robust encryption scheme b This layered encryption model provides strong protection for users’ most sensitive credentials and tokens, while still allowing secure access when needed. -## Secret types +## Secret types \{#secret-types} 'production' | 'test' | undefined | Welche Art von Umgebung, in der Logto läuft. | -| PORT | `3001` | `number` | Der lokale Port, den Logto abhört. | -| ADMIN_PORT | `3002` | `number` | Der lokale Port, den die Logto Admin-Konsole abhört. | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Setze es auf `1` oder `true`, um den Port für die Admin-Konsole zu deaktivieren. Wenn `ADMIN_ENDPOINT` nicht gesetzt ist, wird die Admin-Konsole vollständig deaktiviert. | -| DB_URL | N/A | `string` | Der [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) für die Logto-Datenbank. | -| HTTPS_CERT_PATH | `undefined` | string | undefined | Siehe [Aktivierung von HTTPS](#enabling-https) für Details. | -| HTTPS_KEY_PATH | `undefined` | string | undefined | Ebenso. | -| TRUST_PROXY_HEADER | `false` | `boolean` | Ebenso. | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Du kannst eine URL mit deiner benutzerdefinierten Domain für Online-Tests oder Produktion angeben. Dies wird auch den Wert des [OIDC-Ausstelleridentifikators](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) beeinflussen. | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Du kannst eine URL mit deiner benutzerdefinierten Domain für die Produktion angeben (z. B. `ADMIN_ENDPOINT=https://admin.domain.com`). Dies wird auch den Wert der Admin-Konsole-Umleitungs-URIs beeinflussen. | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Gibt an, ob der Benutzername groß-/kleinsensitiv ist. Sei vorsichtig beim Ändern dieses Wertes; Änderungen werden vorhandene Datenbanken nicht automatisch anpassen, was eine manuelle Verwaltung erfordert. | - -### Aktivierung von HTTPS {#enabling-https} +Bei Standardwerten ist `protocol` entweder `http` oder `https` entsprechend deiner HTTPS-Konfiguration. + +| Key | Standardwert | Typ | Beschreibung | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | In welcher Art von Umgebung Logto ausgeführt wird. | +| PORT | `3001` | `number` | Der lokale Port, auf dem Logto lauscht. | +| ADMIN_PORT | `3002` | `number` | Der lokale Port, auf dem die Logto Admin Console lauscht. | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Setze diesen Wert auf `1` oder `true`, um den Port für die Admin Console zu deaktivieren. Wenn `ADMIN_ENDPOINT` nicht gesetzt ist, wird die Admin Console vollständig deaktiviert. | +| DB_URL | N/A | `string` | Die [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) für die Logto-Datenbank. | +| HTTPS_CERT_PATH | `undefined` | string | undefined | Siehe [HTTPS aktivieren](#enabling-https) für Details. | +| HTTPS_KEY_PATH | `undefined` | string | undefined | Siehe oben. | +| TRUST_PROXY_HEADER | `false` | `boolean` | Siehe oben. | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Du kannst eine URL mit deiner eigenen Domain für Online-Tests oder Produktion angeben. Dies beeinflusst auch den Wert des [OIDC Aussteller-Identifiers](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Du kannst eine URL mit deiner eigenen Domain für die Produktion angeben (z. B. `ADMIN_ENDPOINT=https://admin.domain.com`). Dies beeinflusst auch die Redirect-URIs der Admin Console. | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Gibt an, ob der Benutzername Groß- / Kleinschreibung beachtet. Sei vorsichtig beim Ändern dieses Wertes; Änderungen passen bestehende Daten in der Datenbank nicht automatisch an und erfordern manuelle Verwaltung. | +| SECRET_VAULT_KEK | `undefined` | `string` | Der Key Encryption Key (KEK), der zur Verschlüsselung der Data Encryption Keys (DEK) im [Secret Vault](/secret-vault) verwendet wird. Erforderlich, damit der Secret Vault ordnungsgemäß funktioniert. Muss ein base64-codierter String sein. AES-256 (32 Bytes) wird empfohlen. Beispiel: `crypto.randomBytes(32).toString('base64')` | + +### HTTPS aktivieren {#enabling-https} #### Verwendung von Node {#using-node} @@ -43,22 +44,22 @@ Node unterstützt HTTPS nativ. Gib **SOWOHL** `HTTPS_CERT_PATH` als auch `HTTPS_ #### Verwendung eines HTTPS-Proxys {#using-a-https-proxy} -Eine weitere gängige Praxis ist es, einen HTTPS-Proxy vor Node zu haben (z. B. Nginx). +Eine weitere gängige Praxis ist es, einen HTTPS-Proxy vor Node zu schalten (z. B. Nginx). -In diesem Fall möchtest du wahrscheinlich `TRUST_PROXY_HEADER` auf `true` setzen, was angibt, ob Proxy-Header-Felder vertrauenswürdig sein sollen. Logto wird den Wert an die [Koa-App-Einstellungen](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings) weitergeben. +In diesem Fall möchtest du wahrscheinlich `TRUST_PROXY_HEADER` auf `true` setzen, was angibt, ob Proxy-Header-Felder vertraut werden sollen. Logto gibt den Wert an die [Koa-App-Einstellungen](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings) weiter. -Siehe [Vertrauen in TLS-Offloading-Proxys](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) für Informationen, wann dieses Feld konfiguriert werden sollte. +Siehe [Trusting TLS offloading proxies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies), um zu erfahren, wann dieses Feld konfiguriert werden sollte. -## Datenbankkonfigurationen {#database-configs} +## Datenbank-Konfigurationen {#database-configs} -Das Verwalten zu vieler Umgebungsvariablen ist nicht effizient und flexibel, daher werden die meisten unserer allgemeinen Konfigurationen in der Datenbanktabelle `logto_configs` gespeichert. +Zu viele Umgebungsvariablen zu verwalten ist weder effizient noch flexibel, daher werden die meisten allgemeinen Konfigurationen in der Datenbanktabelle `logto_configs` gespeichert. -Die Tabelle ist ein einfacher Schlüssel-Wert-Speicher, und der Schlüssel ist wie folgt aufzählbar: +Die Tabelle ist eine einfache Key-Value-Speicherung, und der Schlüssel ist wie folgt aufzählbar: -| Schlüssel | Typ | Beschreibung | -| ---------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| oidc.cookieKeys | string[] | Das String-Array der [Signatur-Cookie-Schlüssel](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | -| oidc.privateKeys | string[] | Das String-Array des privaten Schlüsselinhalts für [OIDC JWT-Signierung](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | +| Key | Typ | Beschreibung | +| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| oidc.cookieKeys | string[] | Das String-Array der [Signatur-Cookie-Keys](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | +| oidc.privateKeys | string[] | Das String-Array des privaten Schlüssel-Inhalts für [OIDC JWT-Signierung](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | ### Unterstützte private Schlüsseltypen {#supported-private-key-types} diff --git a/i18n/de/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/de/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index 3f22651f35a..5bf65c76249 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -11,13 +11,13 @@ import Oidc from '@site/docs/connectors/assets/icons/sso-oidc.svg'; import Okta from '@site/docs/connectors/assets/icons/sso-okta.svg'; import Saml from '@site/docs/connectors/assets/icons/sso-saml.svg'; -Die [Single Sign-On (SSO) Lösung](/end-user-flows/enterprise-sso) von Logto vereinfacht das Zugriffsmanagement für deine Unternehmenskunden. Enterprise SSO-Connectors sind entscheidend, um SSO für deine verschiedenen Unternehmenskunden zu ermöglichen. +Die [Single Sign-On (SSO)](/end-user-flows/enterprise-sso)-Lösung von Logto vereinfacht das Zugriffsmanagement für deine Unternehmenskunden. Enterprise SSO-Connectors sind entscheidend, um SSO für deine verschiedenen Unternehmenskunden zu ermöglichen. -Diese Connectors erleichtern den Authentifizierungsprozess zwischen deinem Dienst und den Unternehmens-IdPs. Logto unterstützt sowohl [SP-initiiertes SSO](/end-user-flows/enterprise-sso/sp-initiated-sso) als auch [IdP-initiiertes SSO](/end-user-flows/enterprise-sso/idp-initiated-sso), wodurch Organisationsmitglieder mit ihren bestehenden Unternehmensdaten auf deine Dienste zugreifen können – das erhöht Sicherheit und Produktivität. +Diese Connectors erleichtern den Authentifizierungsprozess zwischen deinem Dienst und den Unternehmens-IdPs. Logto unterstützt sowohl [SP-initiiertes SSO](/end-user-flows/enterprise-sso/sp-initiated-sso) als auch [IdP-initiiertes SSO](/end-user-flows/enterprise-sso/idp-initiated-sso), wodurch Organisationsmitglieder mit ihren bestehenden Unternehmensanmeldedaten auf deine Dienste zugreifen können – das erhöht Sicherheit und Produktivität. ## Enterprise-Connectors \{#enterprise-connectors} -Logto stellt vorgefertigte Connectors für beliebte Enterprise-Identitätsanbieter bereit und ermöglicht so eine schnelle Integration. Für individuelle Anforderungen unterstützen wir die Integration über [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) und [SAML](https://auth.wiki/saml)-Protokolle. +Logto stellt vorgefertigte Connectors für beliebte Unternehmens-Identitätsanbieter bereit, die eine schnelle Integration ermöglichen. Für individuelle Anforderungen unterstützen wir die Integration über die [OpenID Connect (OIDC)](https://auth.wiki/openid-connect)- und [SAML](https://auth.wiki/saml)-Protokolle. ### Beliebte Enterprise-Connectors \{#popular-enterprise-connectors} @@ -83,7 +83,7 @@ Logto stellt vorgefertigte Connectors für beliebte Enterprise-Identitätsanbiet Wenn unsere Standard-Connectors deine spezifischen Anforderungen nicht erfüllen, zögere nicht, uns zu kontaktieren. -## Enterprise-Connectors konfigurieren \{#configuring-enterprise-connectors} +## Konfiguration von Enterprise-Connectors \{#configuring-enterprise-connectors} 1. Navigiere zu: Konsole > Enterprise SSO. 2. Klicke auf die Schaltfläche „Enterprise-Connector hinzufügen“ und wähle einen Connector-Typ aus. @@ -93,17 +93,18 @@ Wenn unsere Standard-Connectors deine spezifischen Anforderungen nicht erfüllen 6. Für den SAML-Enterprise-Connector ist das Aktivieren von IdP-initiiertem SSO im Tab „IdP-initiiertes SSO“ optional. [Siehe Anleitung](/end-user-flows/enterprise-sso/idp-initiated-sso) für Details. 7. Änderungen speichern. -Beachte folgende Einstellungen: +Beachte die folgenden Einstellungen: - **E-Mail-Domains**: Wenn die E-Mail-Domain der vom Benutzer eingegebenen E-Mail im Feld „Enterprise-E-Mail-Domains“ eines Enterprise SSO-Connectors enthalten ist, wird der Benutzer zur entsprechenden Anmelde-URL dieses SSO-Connectors weitergeleitet. :::note Es ist wichtig zu beachten, dass nach der Konfiguration relevanter E-Mail-Domains in einem SSO-Connector Benutzer, die sich mit E-Mails aus diesen Domains anmelden, gezwungen werden, die [SSO-Anmeldung](/end-user-flows/enterprise-sso) zu verwenden. - Anders ausgedrückt: Nur E-Mails von Domains, die NICHT in den SSO-Connectors konfiguriert sind, können die Anmeldung mit „E-Mail + Bestätigungscode“ oder „E-Mail + Passwort“ nutzen (vorausgesetzt, diese beiden Anmeldemethoden sind in der Anmeldeerfahrung aktiviert). + Anders ausgedrückt: Nur E-Mails von Domains, die NICHT in den SSO-Connectors konfiguriert sind, können die Anmeldung mit „E-Mail + Verifizierungscode“ oder „E-Mail + Passwort“ nutzen (sofern diese beiden Anmeldearten in der Anmeldeerfahrung aktiviert sind). ::: -- **Benutzerprofile synchronisieren**: Wähle aus, wann Benutzerprofilinformationen (z. B. Avatar, Name) synchronisiert werden sollen. Das Standardverhalten ist „Nur beim ersten Anmelden synchronisieren“. „Bei jeder Anmeldung immer synchronisieren“ ist eine weitere Option, kann aber dazu führen, dass benutzerdefinierte Benutzerdaten überschrieben werden. +- **Benutzerprofile synchronisieren**: Wähle aus, wann Benutzerprofilinformationen (z. B. Avatar, Name) synchronisiert werden sollen. Das Standardverhalten ist „Nur beim ersten Anmelden synchronisieren“. „Bei jeder Anmeldung immer synchronisieren“ ist eine weitere Option, kann jedoch dazu führen, dass benutzerdefinierte Benutzerdaten überschrieben werden. +- **Token-Speicherung aktivieren**: Für OIDC-Enterprise-Connectors kannst du die Token-Speicherung aktivieren, um Zugangs- und Auffrischungstokens sicher im [Secret Vault](/secret-vault) von Logto zu speichern, wenn sich Benutzer mit einem Enterprise-IdP anmelden. Dadurch kann deine Anwendung im Namen des Benutzers auf Drittanbieter-APIs zugreifen, ohne dass eine erneute Authentifizierung erforderlich ist. Erfahre mehr über [Föderierte Token-Speicherung](/secret-vault/federated-token-set). - **Anzeigedaten**: Optional kannst du den Anzeigenamen und das Logo für den Connector anpassen. Dies ist besonders nützlich, wenn mehrere Connectors mit derselben E-Mail-Domain verknüpft sind. Benutzer wählen dann den gewünschten IdP aus einer Liste von SSO-Connector-Schaltflächen aus, bevor sie zur IdP-Anmeldeseite weitergeleitet werden. ## Enterprise SSO aktivieren \{#enabling-enterprise-sso} @@ -112,7 +113,7 @@ Beachte folgende Einstellungen: 2. Aktiviere den Schalter „Enterprise SSO“. 3. Änderungen speichern. -Nach der Aktivierung erscheint auf deiner Anmeldeseite eine „Single Sign-On“-Schaltfläche. Unternehmenskunden mit SSO-aktivierten E-Mail-Domains können deine Dienste über ihre Enterprise-Identitätsanbieter (IdPs) nutzen. Um mehr über die SSO-Benutzererfahrung zu erfahren, siehe Benutzerflüsse: [Enterprise SSO](/end-user-flows/enterprise-sso). +Nach der Aktivierung erscheint auf deiner Anmeldeseite eine „Single Sign-On“-Schaltfläche. Unternehmenskunden mit SSO-aktivierten E-Mail-Domains können deine Dienste über ihre Unternehmens-Identitätsanbieter (IdPs) nutzen. Um mehr über die SSO-Benutzererfahrung zu erfahren, siehe Benutzerflüsse: [Enterprise SSO](/end-user-flows/enterprise-sso). ## Just-in-Time zur Organisation \{#just-in-time-to-organization} @@ -130,7 +131,7 @@ Logto bietet einen Einstiegspunkt zur Konfiguration der SSO-Connector-JIT-Bereit - SSO hinzufügen: Die SSO-Identitäten werden mit bestehenden Konten verknüpft, wenn die E-Mail übereinstimmt. -- SSO entfernen: Entfernt SSO-Identitäten, die mit dem Konto verknüpft sind, behält aber Benutzerkonten bei und fordert Benutzer auf, alternative Verifizierungsmethoden einzurichten. +- SSO entfernen: Entfernt SSO-Identitäten, die mit dem Konto verknüpft sind, behält aber Benutzerkonten bei und fordert die Benutzer auf, alternative Verifizierungsmethoden einzurichten. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/de/docusaurus-plugin-content-docs/current/connectors/social.mdx index 3a0e70b4cae..5184e3a1e2f 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,15 +7,15 @@ sidebar_position: 3 # Soziale Connectors -Vereinfache das Benutzer-Onboarding und erhöhe die Konversionsraten, indem du die [soziale Anmeldung](/end-user-flows/sign-up-and-sign-in/social-sign-in) mit Logto aktivierst. Benutzer können sich schnell und sicher mit ihren bestehenden Social-Media-Konten anmelden, was die Notwendigkeit der Passworterstellung oder eines komplexen Registrierungsprozesses eliminiert. Logto bietet eine Vielzahl von vorgefertigten sozialen Connectors und unterstützt benutzerdefinierte Integrationen für maximale Flexibilität. +Vereinfache das Onboarding von Benutzern und erhöhe die Konversionsraten, indem du [soziale Anmeldung](/end-user-flows/sign-up-and-sign-in/social-sign-in) mit Logto aktivierst. Benutzer können sich schnell und sicher mit ihren bestehenden Social-Media-Konten anmelden, wodurch die Notwendigkeit zur Passworterstellung oder eines komplexen Registrierungsprozesses entfällt. Logto bietet eine Vielzahl von vorgefertigten sozialen Connectors und unterstützt individuelle Integrationen für maximale Flexibilität. ## Wähle deine sozialen Connectors \{#choose-your-social-connectors} -Logto bietet zwei Arten von sozialen Connectors: +Logto bietet zwei Arten von sozialen Connectors an: ### Beliebte soziale Connectors \{#popular-social-connectors} -Logto bietet vorkonfigurierte Connectors für beliebte soziale Plattformen, die sofort einsatzbereit sind. +Logto stellt vorkonfigurierte Connectors für beliebte soziale Plattformen bereit, die sofort einsatzbereit sind. ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'Der Google-Connector bietet eine prägnante Möglichkeit für deine Anwendung, das OAuth 2.0-Authentifizierungssystem von Google zu nutzen.', + description: 'Der Google-Connector bietet eine einfache Möglichkeit für deine Anwendung, das OAuth 2.0-Authentifizierungssystem von Google zu nutzen.', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'Der Facebook-Connector ermöglicht es deiner Anwendung, das OAuth 2.0-Authentifizierungssystem von Facebook zu nutzen.', + description: 'Der Facebook-Connector ermöglicht deiner Anwendung die Nutzung des OAuth 2.0-Authentifizierungssystems von Facebook.', customProps: { icon: , } @@ -52,7 +52,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Apple', href: '/integrations/apple', - description: 'Der offizielle Logto-Connector für die soziale Anmeldung bei Apple.', + description: 'Der offizielle Logto-Connector für Apple Social Sign-in.', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'Der Microsoft Azure AD-Connector bietet eine prägnante Möglichkeit für deine Anwendung, das OAuth 2.0-Authentifizierungssystem von Azure zu nutzen.', + description: 'Der Microsoft Azure AD-Connector bietet eine einfache Möglichkeit für deine Anwendung, das OAuth 2.0-Authentifizierungssystem von Azure zu nutzen.', customProps: { icon: , } @@ -70,7 +70,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'GitHub', href: '/integrations/github', - description: 'Der offizielle Logto-Connector für die soziale Anmeldung bei GitHub.', + description: 'Der offizielle Logto-Connector für GitHub Social Sign-in.', customProps: { icon: , } @@ -92,7 +92,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; ### Passe deine sozialen Connectors an \{#customize-your-social-connectors} -Für benutzerdefinierte Anforderungen nutze die OAuth 2.0- und OIDC (OpenID Connect)-Standards, um deinen bevorzugten Anbieter zu integrieren. +Für individuelle Anforderungen nutze die OAuth 2.0- und OIDC (OpenID Connect)-Standards, um deinen bevorzugten Anbieter zu integrieren. ```mdx-code-block ``` -Wenn unsere Standard-Connectors deine spezifischen Anforderungen nicht erfüllen, zögere nicht, [kontaktiere uns](https://logto.productlane.com/roadmap). Für OSS-Nutzer kannst du [deinen Connector implementieren (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector), wenn die Anforderung dringend ist. Wir begrüßen immer [Beiträge](/logto-oss/contribution); dein Einsatz könnte anderen Community-Mitgliedern mit denselben Bedürfnissen sehr helfen. +Wenn unsere Standard-Connectors deine spezifischen Anforderungen nicht erfüllen, zögere nicht, [uns zu kontaktieren](https://logto.productlane.com/roadmap). Für OSS-Nutzer kannst du [deinen eigenen Connector implementieren (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector), falls die Anforderung dringend ist. Wir freuen uns immer über [Beiträge](/logto-oss/contribution); dein Einsatz könnte auch anderen Community-Mitgliedern mit denselben Bedürfnissen helfen. ## Konfigurationsschritte \{#configuration-steps} 1. Navigiere zu Konsole > Connectors > Soziale Connectors. -2. Klicke auf "Sozialen Connector hinzufügen" und wähle den gewünschten Typ aus. -3. Folge der README-Anleitung und fülle die erforderlichen Felder aus und passe die Einstellungen an. -4. Klicke auf "Speichern und Fertig", um abzuschließen. +2. Klicke auf „Sozialen Connector hinzufügen“ und wähle den gewünschten Typ aus. +3. Folge der README-Anleitung, fülle die erforderlichen Felder aus und passe die Einstellungen an. +4. Klicke auf „Speichern und Fertigstellen“, um abzuschließen. 5. Teste den Connector, indem du eine soziale Anmeldung initiierst. Bitte beachte die folgenden Einstellungen: -- **Name des Identitätsanbieters**: Jeder soziale Connector hat einen einzigartigen Namen des Identitätsanbieters (IdP), um Benutzeridentitäten zu unterscheiden. Während gängige Connectors einen festen IdP-Namen verwenden, erfordern benutzerdefinierte Connectors einen einzigartigen Wert. Erfahre mehr über [IdP-Namen](/connectors/connector-data-structure#target-identity-provider-name) für weitere Details. -- **Benutzerprofile synchronisieren**: Wähle, wann [Benutzerprofilinformationen](/user-management/user-data#social-identities) (z. B. Avatar, Benutzername) synchronisiert werden sollen. Standardmäßig wird "nur bei Registrierung synchronisieren" verwendet. "Bei jeder Anmeldung synchronisieren" ist eine Alternative, kann jedoch benutzerdefinierte Benutzerdaten überschreiben. +- **Identity Provider Name**: Jeder soziale Connector hat einen eindeutigen Identity Provider (IdP)-Namen, um Benutzeridentitäten zu unterscheiden. Während gängige Connectors einen festen IdP-Namen verwenden, benötigen benutzerdefinierte Connectors einen eindeutigen Wert. Erfahre mehr über [IdP-Namen](/connectors/connector-data-structure#target-identity-provider-name) für weitere Details. +- **Benutzerprofile synchronisieren**: Wähle, wann [Benutzerprofilinformationen](/user-management/user-data#social-identities) (z. B. Avatar, Benutzername) synchronisiert werden sollen. Standardmäßig wird „nur bei Registrierung synchronisieren“ verwendet. „Bei jeder Anmeldung synchronisieren“ ist eine Alternative, kann jedoch benutzerdefinierte Benutzerdaten überschreiben. +- **Token-Speicherung aktivieren**: Für unterstützte soziale Connectors kannst du die Token-Speicherung aktivieren, um Zugangs- und Auffrischungstokens sicher im Logto [Secret Vault](/secret-vault) zu speichern, wenn Benutzer sich mit einem sozialen Anbieter anmelden. Dadurch kann deine Anwendung auf Drittanbieter-APIs im Namen des Benutzers zugreifen, ohne dass eine erneute Authentifizierung erforderlich ist. Erfahre mehr über [Föderierte Token-Speicherung](/secret-vault/federated-token-set). ## Soziale Anmeldung aktivieren \{#enable-social-sign-in} -Sobald du erfolgreich einen sozialen Connector erstellt hast, kannst du ihn als Social-Login-Button (z. B. Weiter mit Google) in der Anmeldeerfahrung aktivieren. +Sobald du einen sozialen Connector erfolgreich erstellt hast, kannst du ihn als Social-Login-Button (z. B. „Mit Google fortfahren“) in der Anmeldeerfahrung aktivieren. -1. Navigiere zu Konsole > Anmeldeerfahrung > Anmeldung und Registrierung. -2. (Optional) Wähle "Nicht zutreffend" für das Anmeldekennzeichen, wenn du nur die soziale Anmeldung benötigst. -3. Füge konfigurierte soziale Connectors zum Abschnitt "Soziale Anmeldung" hinzu. -4. Ordne die Connectors nach Bedarf neu. -5. Klicke auf "Änderungen speichern" und teste die "Live-Vorschau". +1. Navigiere zu Konsole > Anmeldeerfahrung > Registrierung und Anmeldung. +2. (Optional) Wähle „Nicht zutreffend“ als Registrierungskennzeichen, wenn du nur soziale Anmeldung benötigst. +3. Füge konfigurierte soziale Connectors zum Abschnitt „Soziale Anmeldung“ hinzu. +4. Ordne die Connectors nach Bedarf neu an. +5. Klicke auf „Änderungen speichern“ und teste die „Live-Vorschau“. Siehe [Soziale Anmeldung](/end-user-flows/sign-up-and-sign-in/social-sign-in), um mehr über die Details zu erfahren. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index cee491e8ec7..47faa92c774 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -10,20 +10,65 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Soziale Anmeldung mit Facebook einrichten +# Soziale Anmeldung mit Facebook einrichten (Set up social login with Facebook) -Der offizielle Logto-Connector für die Facebook-Sozialanmeldung. +Integriere das Facebook OAuth 2.0-Authentifizierungssystem, um „Mit Facebook anmelden“, Kontoverknüpfung und sicheren Zugriff auf Facebook APIs zu ermöglichen. ## Erste Schritte \{#get-started} -Der Facebook-Connector bietet eine prägnante Möglichkeit für deine Anwendung, das OAuth 2.0-Authentifizierungssystem von Facebook zu nutzen. +Der Facebook Connector ermöglicht die OAuth 2.0-Integration, damit deine Anwendung: + +- Die Authentifizierung „Mit Facebook anmelden“ hinzufügen kann +- Benutzerkonten mit Facebook-Identitäten verknüpfen kann +- Benutzerprofilinformationen von Facebook synchronisieren kann +- Auf Facebook APIs über sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben zugreifen kann (z. B. auf Threads antworten; Inhalte und Videos in deiner App veröffentlichen) + +Um diese Authentifizierungsfunktionen einzurichten, erstelle zuerst einen Facebook Connector in Logto: + +1. Gehe zu [Logto > Connector > Social connector](https://cloud.logto.io/to/connectors/social). +2. Klicke auf **Sozialen Connector hinzufügen**, wähle **Facebook**, klicke auf **Weiter** und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen. -## Referenzen \{#references} +## Den Facebook Connector nutzen \{#utilize-the-facebook-connector} + +Sobald du einen Facebook Connector erstellt und mit Facebook verbunden hast, kannst du ihn in deine Endnutzer-Flows einbinden. Wähle die Optionen, die zu deinen Anforderungen passen: + +### „Mit Facebook anmelden“ aktivieren \{#enable-sign-in-with-facebook} + +1. Gehe in der Logto Console zu Anmeldeerfahrung > Registrierung und Anmeldung +2. Füge den Facebook Connector im Abschnitt **Soziale Anmeldung** hinzu, damit sich Benutzer mit Facebook authentifizieren können + +Erfahre mehr über die [soziale Anmeldeerfahrung](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Ein Facebook-Konto verknüpfen oder trennen \{#link-or-unlink-a-facebook-account} + +Nutze die Account API, um ein individuelles Account Center in deiner App zu erstellen, das angemeldeten Benutzern ermöglicht, ihr Facebook-Konto zu verknüpfen oder zu trennen. [Folge dem Account API Tutorial](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Es ist möglich, den Facebook Connector nur für die Kontoverknüpfung und den API-Zugriff zu aktivieren, ohne ihn für die soziale Anmeldung zu aktivieren. +::: + +### Auf die Facebook API zugreifen und Aktionen durchführen \{#access-facebook-api-and-perform-actions} + +Deine Anwendung kann gespeicherte Facebook Zugangstokens (Access tokens) aus dem Secret Vault abrufen, um Facebook APIs aufzurufen und Backend-Aufgaben zu automatisieren (zum Beispiel Inhalte veröffentlichen oder Beiträge verwalten). Siehe die Anleitung zum Abrufen gespeicherter Tokens für den API-Zugriff. + +## Die Facebook-Identität eines Benutzers verwalten \{#manage-user-s-facebook-identity} + +Nachdem ein Benutzer sein Facebook-Konto verknüpft hat, können Administratoren diese Verbindung in der Logto Console verwalten: + +1. Navigiere zu Benutzerverwaltung und öffne das Benutzerprofil. +2. Unter **Soziale Verbindungen** finde den Facebook-Eintrag und klicke auf **Verwalten**. +3. Auf dieser Seite können Administratoren die Facebook-Verbindung des Benutzers verwalten, alle gewährten und von Facebook synchronisierten Profilinformationen einsehen und den Status des Zugangstokens (Access token) überprüfen. + +:::note +Die Access token-Antwort von Facebook enthält keine spezifischen Scope-Informationen, daher kann Logto die vom Benutzer gewährten Berechtigungen nicht direkt anzeigen. Solange der Benutzer jedoch den angeforderten Berechtigungen (Scopes) während der Autorisierung zugestimmt hat, verfügt deine Anwendung beim Zugriff auf die Facebook API über die entsprechenden Berechtigungen. Es wird empfohlen, die erforderlichen Berechtigungen sowohl in der Facebook Developer Console als auch in Logto korrekt zu konfigurieren, um sicherzustellen, dass deine App den notwendigen Zugriff hat. +::: + +## Referenz \{#reference} + +Facebook for Developers – Dokumentation -- [Facebook Login - Dokumentation - Facebook für Entwickler](https://developers.facebook.com/docs/facebook-login/) - - [Manuelles Erstellen eines Anmeldeflusses](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [Berechtigungsleitfaden](https://developers.facebook.com/docs/facebook-login/guides/permissions) +Facebook Login Dokumentation diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index 8fd5a6034b5..d467ab7d0a4 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,54 +1,100 @@ -### Ein Facebook-Entwicklerkonto registrieren \{#register-a-facebook-developer-account} +## Schritt 1: Eine App im Facebook App Dashboard einrichten \{#step-1-set-up-an-app-on-facebook-app-dashboard} -[Registriere dich als Facebook-Entwickler](https://developers.facebook.com/docs/development/register/), falls du noch kein Konto hast. +Bevor du Facebook als Authentifizierungsanbieter verwenden kannst, musst du eine App auf der Facebook-Entwicklerplattform einrichten, um OAuth 2.0-Zugangsdaten zu erhalten. -### Eine Facebook-App einrichten \{#set-up-a-facebook-app} +1. [Registriere dich als Facebook-Entwickler](https://developers.facebook.com/docs/development/register/), falls du noch kein Konto hast. +2. Besuche die Seite [Apps](https://developers.facebook.com/apps). +3. Klicke auf deine bestehende App oder [erstelle eine neue](https://developers.facebook.com/docs/development/create-an-app), falls nötig. -1. Besuche die [Apps](https://developers.facebook.com/apps) Seite. -2. Klicke auf deine bestehende App oder [erstelle eine neue](https://developers.facebook.com/docs/development/create-an-app), falls nötig. - - Der ausgewählte [App-Typ](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types) liegt bei dir, sollte aber das Produkt _Facebook Login_ enthalten. -3. Auf der App-Dashboard-Seite scrolle zum Abschnitt "Produkt hinzufügen" und klicke auf die Schaltfläche "Einrichten" auf der Karte "Facebook Login". -4. Überspringe die Facebook Login Schnellstartseite und klicke auf die Seitenleiste -> "Produkte" -> "Facebook Login" -> "Einstellungen". -5. Auf der Seite Facebook Login Einstellungen fülle `${your_logto_origin}/callback/${connector_id}` im Feld "Gültige OAuth-Weiterleitungs-URIs" aus. Die `connector_id` findest du in der oberen Leiste der Logto Admin Console Connector-Detailseite. Zum Beispiel: - - `https://logto.dev/callback/${connector_id}` für die Produktion - - `https://localhost:3001/callback/${connector_id}` für Tests in der lokalen Umgebung -6. Klicke auf die Schaltfläche "Änderungen speichern" in der unteren rechten Ecke. +:::tip +Ein Anwendungsfall ist die primäre Art und Weise, wie deine App mit Meta interagiert und bestimmt, welche APIs, Funktionen, Berechtigungen und Produkte deiner App zur Verfügung stehen. Wenn du nur soziale Authentifizierung benötigst (um E-Mail & public_profile zu erhalten), wähle „Authentifizierung und Anfragedaten von Benutzern mit Facebook Login“. Wenn du auf Facebook-APIs zugreifen möchtest, wähle deine bevorzugten Anwendungsfälle – die meisten unterstützen auch die Integration von „Facebook Login for business“ nach der App-Erstellung. +::: -## Den Connector-JSON zusammenstellen \{#compose-the-connector-json} +4. Nach der App-Erstellung navigiere im App-Dashboard zu **Use cases > Facebook Login > Settings** oder **Facebook Login for business > Settings**. +5. Fülle das Feld **Valid OAuth Redirect URIs** mit der Logto **Callback URI** aus (kopiere diese aus deinem Logto Facebook Connector). Nachdem sich Benutzer mit Facebook angemeldet haben, werden sie hierher mit einem Autorisierungscode weitergeleitet, den Logto zur Fertigstellung der Authentifizierung verwendet. +6. Navigiere zu **Use cases** und klicke auf **Customize** deines Anwendungsfalls, um die Berechtigungen (Scopes) hinzuzufügen. Wir empfehlen, `email` und `public_profile` hinzuzufügen, die für die Implementierung der Anmeldung mit Facebook in Logto erforderlich sind. -1. Auf der Facebook-App-Dashboard-Seite klicke auf die Seitenleiste -> "Einstellungen" -> "Grundlegend". -2. Du siehst die "App-ID" und das "App-Geheimnis" auf dem Panel. -3. Klicke auf die Schaltfläche "Anzeigen" neben dem Eingabefeld für das App-Geheimnis, um dessen Inhalt zu kopieren. -4. Fülle die Logto-Connector-Einstellungen aus: - - Fülle das Feld `clientId` mit dem String aus _App-ID_ aus. - - Fülle das Feld `clientSecret` mit dem String aus _App-Geheimnis_ aus. - - Fülle das Feld `scope` mit einer durch Kommas oder Leerzeichen getrennten Liste von [Berechtigungen](https://developers.facebook.com/docs/permissions/reference) als String aus. Wenn du keinen Scope angibst, ist der Standard-Scope `email,public_profile`. +## Schritt 2: Logto Connector mit Client-Zugangsdaten einrichten \{#step-2-set-up-logto-connector-with-client-credentials} -## Anmeldung mit Facebook-Testbenutzern testen \{#test-sign-in-with-facebooks-test-users} +1. Klicke im Facebook App Dashboard in der Seitenleiste auf **App settings > Basic**. +2. Du siehst die **App ID** und das **App secret** im Panel. +3. Klicke auf die Schaltfläche **Show** neben dem Eingabefeld für das App secret, um den Inhalt anzuzeigen und zu kopieren. +4. Konfiguriere deine Logto Facebook Connector-Einstellungen: + - Trage in das Feld `clientId` die **App ID** ein. + - Trage in das Feld `clientSecret` das **App secret** ein. + - Klicke in Logto auf **Save and Done**, um dein Identitätssystem mit Facebook zu verbinden. -Du kannst die Konten der Test-, Entwickler- und Admin-Benutzer verwenden, um die Anmeldung mit der zugehörigen App sowohl im Entwicklungs- als auch im Live-[App-Modus](https://developers.facebook.com/docs/development/build-and-test/app-modes) zu testen. +## Schritt 3: Berechtigungen (Scopes) konfigurieren \{#step-3-configure-scopes} -Du kannst die App auch direkt [live schalten](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode), sodass sich jeder Facebook-Benutzer mit der App anmelden kann. +Berechtigungen (Scopes) definieren, welche Zugriffsrechte deine App von den Benutzern anfordert und steuern, auf welche privaten Daten dein Projekt aus deren Facebook-Konten zugreifen kann. -- Auf der App-Dashboard-Seite klicke auf die Seitenleiste -> "Rollen" -> "Testbenutzer". -- Klicke auf die Schaltfläche "Testbenutzer erstellen", um einen Testbenutzer zu erstellen. -- Klicke auf die Schaltfläche "Optionen" des bestehenden Testbenutzers, und du siehst weitere Operationen, z. B. "Name und Passwort ändern". +### Berechtigungen im Facebook App Dashboard konfigurieren \{#configure-scopes-in-facebook-app-dashboard} -## Facebook-Anmeldeeinstellungen veröffentlichen \{#publish-facebook-sign-in-settings} +1. Navigiere zu **Facebook App Dashboard > Use cases** und klicke auf die Schaltfläche **Customize**. +2. Füge nur die Berechtigungen hinzu, die deine App benötigt. Die Benutzer werden diese Berechtigungen auf dem Facebook Zustimmungsbildschirm (Consent screen) überprüfen und autorisieren: + - **Für Authentifizierung (erforderlich)**: `email` und `public_profile`. + - **Für API-Zugriff (optional)**: Alle zusätzlichen Berechtigungen, die deine App benötigt (z. B. `threads_content_publish`, `threads_read_replies` für den Zugriff auf die Threads API). Siehe die [Meta Developer Documentation](https://developers.facebook.com/docs/) für verfügbare Dienste. -Normalerweise können sich nur die Test-, Admin- und Entwickler-Benutzer mit der zugehörigen App im [Entwicklungsmodus](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode) anmelden. +### Berechtigungen in Logto konfigurieren \{#configure-scopes-in-logto} -Um normalen Facebook-Benutzern die Anmeldung mit der App in der Produktionsumgebung zu ermöglichen, musst du möglicherweise deine Facebook-App in den _[Live-Modus](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_ schalten, abhängig vom App-Typ. Zum Beispiel hat die reine _Business-Typ_ App keinen "Live"-Schalter, aber es wird deine Nutzung nicht blockieren. +Wähle je nach Bedarf eine oder mehrere der folgenden Vorgehensweisen: -1. Auf der Facebook-App-Dashboard-Seite klicke auf die Seitenleiste -> "Einstellungen" -> "Grundlegend". -2. Fülle die Felder "Datenschutzrichtlinien-URL" und "Benutzerdatenlöschung" auf dem Panel aus, falls erforderlich. -3. Klicke auf die Schaltfläche "Änderungen speichern" in der unteren rechten Ecke. -4. Klicke auf die "Live"-Schaltfläche in der oberen Leiste der App. +**Option 1: Keine zusätzlichen API-Berechtigungen benötigt** -## Konfigurationstypen \{#config-types} +- Lasse das Feld `Scopes` in deinem Logto Facebook Connector leer. +- Die Standardberechtigungen `email public_profile` werden angefordert, damit Logto grundlegende Benutzerinformationen korrekt abrufen kann. -| Name | Typ | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**Option 2: Zusätzliche Berechtigungen bei der Anmeldung anfordern** + +- Gib alle gewünschten Berechtigungen im Feld **Scopes** ein, getrennt durch Leerzeichen. +- Alle hier aufgeführten Berechtigungen überschreiben die Standardwerte, daher immer auch die Authentifizierungsberechtigungen `email public_profile` angeben. + +**Option 3: Spätere Anforderung zusätzlicher Berechtigungen** + +- Nachdem sich der Benutzer angemeldet hat, kannst du bei Bedarf zusätzliche Berechtigungen anfordern, indem du einen föderierten sozialen Autorisierungsfluss erneut startest und das gespeicherte Token-Set des Benutzers aktualisierst. +- Diese zusätzlichen Berechtigungen müssen nicht im Feld `Scopes` deines Logto Facebook Connectors eingetragen werden und können über die Logto Social Verification API erreicht werden. + +Wenn du diese Schritte befolgst, fordert dein Logto Facebook Connector genau die Berechtigungen an, die deine App benötigt – nicht mehr und nicht weniger. + +:::tip +Wenn deine App diese Berechtigungen anfordert, um auf die Facebook API zuzugreifen und Aktionen auszuführen, aktiviere **Store tokens for persistent API access** im Logto Facebook Connector. Siehe den nächsten Abschnitt für Details. +::: + +## Schritt 4: Allgemeine Einstellungen \{#step-4-general-settings} + +Hier sind einige allgemeine Einstellungen, die die Verbindung zu Facebook nicht blockieren, aber die Authentifizierungserfahrung für Endbenutzer beeinflussen können. + +### Profilinformationen synchronisieren \{#sync-profile-information} + +Im Facebook Connector kannst du die Richtlinie für die Synchronisierung von Profilinformationen wie Benutzernamen und Avataren festlegen. Wähle aus: + +- **Nur bei Registrierung synchronisieren**: Profilinformationen werden einmalig beim ersten Anmelden des Benutzers abgerufen. +- **Immer bei Anmeldung synchronisieren**: Profilinformationen werden bei jeder Anmeldung des Benutzers aktualisiert. + +### Tokens speichern, um auf Facebook APIs zuzugreifen (optional) \{#store-tokens-to-access-facebook-apis-optional} + +Wenn du auf Facebook APIs zugreifen und Aktionen mit Benutzerautorisierung durchführen möchtest (egal ob über soziale Anmeldung oder Kontoverknüpfung), muss Logto bestimmte API-Berechtigungen erhalten und Tokens speichern. + +1. Füge die erforderlichen Berechtigungen gemäß obigem Tutorial hinzu. +2. Aktiviere **Store tokens for persistent API access** im Logto Facebook Connector. Logto speichert Facebook Zugangstokens sicher im Secret Vault. + +:::note +Facebook stellt keine Auffrischungstokens (Refresh tokens) bereit. Wenn jedoch die Token-Speicherung aktiviert ist, fordert Logto bei der Benutzer-Authentifizierung automatisch ein langlebiges Zugangstoken (60 Tage) an. Während dieses Zeitraums können Benutzer Zugangstokens manuell widerrufen, müssen aber ansonsten keine erneute Autorisierung durchführen, um auf Facebook APIs zuzugreifen. Hinweis: Füge `offline_access` nicht zum Feld `Scope` hinzu, da dies zu Fehlern führen kann. +::: + +## Schritt 5: Anmeldung mit Facebook-Testbenutzern testen (optional) \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +Du kannst Test-, Entwickler- und Administratorkonten verwenden, um die Anmeldung mit der App zu testen. Du kannst die App auch direkt veröffentlichen, sodass sich jeder Facebook-Benutzer anmelden kann. + +1. Klicke im Facebook App Dashboard in der Seitenleiste auf **App roles > Test Users**. +2. Klicke auf die Schaltfläche **Create test users**, um einen Testbenutzer zu erstellen. +3. Klicke auf die Schaltfläche **Options** eines bestehenden Testbenutzers, um weitere Aktionen wie „Name und Passwort ändern“ anzuzeigen. + +## Schritt 6: Facebook-Anmeldeeinstellungen veröffentlichen \{#step-6-publish-facebook-sign-in-settings} + +In der Regel können sich nur Test-, Administrator- und Entwicklerbenutzer mit der App anmelden. Um normalen Facebook-Benutzern die Anmeldung mit der App in der Produktionsumgebung zu ermöglichen, musst du die App möglicherweise veröffentlichen. + +1. Klicke im Facebook App Dashboard in der Seitenleiste auf **Publish**. +2. Fülle die Felder **Privacy Policy URL** und **User data deletion** aus, falls erforderlich. +3. Klicke auf die Schaltfläche **Save changes** unten rechts. +4. Klicke auf die **Live**-Umschaltschaltfläche in der oberen Leiste der App. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index b9c9a2d79c8..49654a0aa17 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -3,7 +3,7 @@ slug: /integrations/github sidebar_label: GitHub sidebar_custom_props: darkLogoFilename: 'github-dark.svg' - description: GitHub ist eine Online-Community für Softwareentwicklung und Versionskontrolle. + description: GitHub ist eine Online-Community für Softwareentwicklung und Versionskontrolle. (GitHub is an online community for software development and version control.) tutorial_config_name: GitHub OAuth app --- @@ -11,28 +11,73 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Soziale Anmeldung mit GitHub einrichten +# Soziale Anmeldung mit GitHub einrichten (Set up social login with GitHub) -Der offizielle Logto-Connector für die GitHub-Sozialanmeldung. +Integriere die GitHub OAuth-App, um „Mit GitHub anmelden“, Kontoverknüpfung und sicheren Zugriff auf GitHub APIs zu ermöglichen. ## Erste Schritte \{#get-started} -Der GitHub-Connector ermöglicht es Endbenutzern, sich über ihre eigenen GitHub-Konten mithilfe des GitHub OAuth 2.0-Authentifizierungsprotokolls bei deiner Anwendung anzumelden. +Der GitHub Connector ermöglicht die OAuth 2.0-Integration, damit deine Anwendung: + +- Die Authentifizierung „Mit GitHub anmelden“ hinzufügt +- Benutzerkonten mit GitHub-Identitäten verknüpft +- Benutzerprofilinformationen von GitHub synchronisiert +- Auf GitHub APIs über sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben zugreift (z. B. Erstellen von GitHub-Issues, Verwalten von Repositories aus deiner App) + +Um diese Authentifizierungsfunktionen einzurichten, erstelle zuerst einen GitHub Connector in Logto: + +1. Gehe zu Logto-Konsole > Connector > Social Connector. +2. Klicke auf **Social Connector hinzufügen**, wähle **GitHub**, klicke auf **Weiter** und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen. -## GitHub-Connector testen \{#test-github-connector} +## Den GitHub Connector nutzen \{#utilize-the-github-connector} + +Nachdem du einen GitHub Connector erstellt und mit GitHub verbunden hast, kannst du ihn in deine Endbenutzer-Flows einbinden. Wähle die Optionen, die zu deinen Anforderungen passen: + +### „Mit GitHub anmelden“ aktivieren \{#enable-sign-in-with-github} + +1. Gehe in der Logto-Konsole zu Anmeldeerfahrung > Registrierung und Anmeldung. +2. Füge den GitHub Connector im Abschnitt **Soziale Anmeldung** hinzu, damit Benutzer sich mit GitHub authentifizieren können. + +Erfahre mehr über die [soziale Anmeldeerfahrung](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Ein GitHub-Konto verknüpfen oder trennen \{#link-or-unlink-a-github-account} + +Nutze die Account API, um ein individuelles Account Center in deiner App zu erstellen, in dem angemeldete Benutzer ihr GitHub-Konto verknüpfen oder trennen können. [Folge dem Account API-Tutorial](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -Das war's. Der GitHub-Connector sollte jetzt verfügbar sein. Vergiss nicht, [Sozialen Connector in der Anmeldeerfahrung aktivieren](/connectors/social-connectors/#enable-social-sign-in). +:::tip +Es ist möglich, den GitHub Connector nur für die Kontoverknüpfung und den API-Zugriff zu aktivieren, ohne ihn für die soziale Anmeldung zu aktivieren. +::: + +### Auf GitHub APIs zugreifen und Aktionen ausführen \{#access-github-apis-and-perform-actions} + +Deine Anwendung kann gespeicherte GitHub Zugangstokens aus dem Secret Vault abrufen, um GitHub APIs aufzurufen und Backend-Aufgaben zu automatisieren (z. B. Issues erstellen, Repositories verwalten oder Workflows automatisieren). Siehe die Anleitung zum Abrufen gespeicherter Tokens für den API-Zugriff. + +## GitHub-Identität des Benutzers verwalten \{#manage-user-s-github-identity} + +Nachdem ein Benutzer sein GitHub-Konto verknüpft hat, können Administratoren diese Verbindung in der Logto-Konsole verwalten: + +1. Navigiere zu Logto-Konsole > Benutzerverwaltung und öffne das Profil des Benutzers. +2. Unter **Soziale Verbindungen** finde den GitHub-Eintrag und klicke auf **Verwalten**. +3. Auf dieser Seite können Administratoren die GitHub-Verbindung des Benutzers verwalten, alle aus dem GitHub-Konto gewährten und synchronisierten Profilinformationen einsehen und den Status des Zugangstokens prüfen. + +:::note +Die Antwort des GitHub Zugangstokens enthält keine spezifischen Berechtigungsinformationen (Scopes), daher kann Logto die vom Benutzer gewährten Berechtigungen nicht direkt anzeigen. Solange der Benutzer jedoch den angeforderten Berechtigungen während der Autorisierung zugestimmt hat, verfügt deine Anwendung beim Zugriff auf die GitHub API über die entsprechenden Berechtigungen. +::: ## Referenz \{#reference} - GitHub - Entwickler - Apps + GitHub Entwicklerdokumentation – Über Apps - GitHub - Entwickler - Apps - Erstellen einer OAuth-App + GitHub Entwicklerdokumentation – Erstellen einer OAuth-App + + + + GitHub OAuth App Scopes Dokumentation diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index 46d2dfc3ce0..4ae2d6c1c0b 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,35 +1,99 @@ -### Mit GitHub-Konto anmelden \{#sign-in-with-github-account} +## Schritt 1: Erstelle eine OAuth-App auf GitHub \{#step-1-create-an-oauth-app-on-github} -Gehe zur [GitHub-Website](https://github.com/) und melde dich mit deinem GitHub-Konto an. Du kannst ein neues Konto registrieren, wenn du noch keines hast. +Bevor du GitHub als Authentifizierungsanbieter verwenden kannst, musst du eine OAuth-App auf GitHub erstellen, um OAuth 2.0-Zugangsdaten zu erhalten. -### OAuth-App erstellen und konfigurieren \{#create-and-configure-oauth-app} +1. Gehe zu [GitHub](https://github.com/) und melde dich mit deinem Konto an oder erstelle bei Bedarf ein neues Konto. +2. Navigiere zu [Einstellungen > Entwicklereinstellungen > OAuth-Apps](https://github.com/settings/developers). +3. Klicke auf **Neue OAuth-App**, um eine neue Anwendung zu registrieren: + - **Anwendungsname**: Gib einen aussagekräftigen Namen für deine App ein. + - **Homepage-URL**: Gib die Homepage-URL deiner Anwendung ein. + - **Autorisierungs-Callback-URL**: Kopiere die **Callback-URI** aus deinem Logto GitHub Connector und füge sie hier ein. Nachdem sich Benutzer mit GitHub angemeldet haben, werden sie hierher mit einem Autorisierungscode weitergeleitet, den Logto verwendet, um die Authentifizierung abzuschließen. + - **Anwendungsbeschreibung**: (Optional) Füge eine kurze Beschreibung deiner App hinzu. +4. Klicke auf **Anwendung registrieren**, um die OAuth-App zu erstellen. -Folge der Anleitung zum [Erstellen einer OAuth-App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) und registriere eine neue Anwendung. +:::note +Wir empfehlen, das Kontrollkästchen **Device Flow aktivieren** nicht zu markieren, da Benutzer, die sich mit GitHub auf mobilen Geräten anmelden, die anfängliche Anmeldeaktion in der GitHub Mobile App bestätigen müssten. Viele GitHub-Nutzer installieren die GitHub Mobile App nicht auf ihren Handys, was den Anmeldevorgang blockieren könnte. Aktiviere dies nur, wenn du erwartest, dass Endbenutzer ihren Anmeldevorgang über die GitHub Mobile App bestätigen. Siehe Details zum [Device Flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). -Benenne deine neue OAuth-Anwendung im Feld **Application name** und fülle die **Homepage URL** der App aus. Du kannst das Feld **Application description** leer lassen und die **Authorization callback URL** als `${your_logto_origin}/callback/${connector_id}` anpassen. Die `connector_id` findest du in der oberen Leiste der Logto Admin Console auf der Seite mit den Connector-Details. +Weitere Informationen zum Einrichten von GitHub OAuth-Apps findest du unter [Erstellen einer OAuth-App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). +::: -:::note +## Schritt 2: Konfiguriere deinen Logto Connector \{#step-2-configure-your-logto-connector} + +Nachdem du die OAuth-App in GitHub erstellt hast, wirst du zu einer Detailseite weitergeleitet, auf der du die Client-ID kopieren und ein Client-Geheimnis generieren kannst. + +1. Kopiere die **Client-ID** aus deiner GitHub OAuth-App und füge sie in das Feld `clientId` in Logto ein. +2. Klicke in GitHub auf **Neues Client-Geheimnis generieren**, um ein neues Geheimnis zu erstellen, und kopiere und füge es dann in das Feld `clientSecret` in Logto ein. +3. Klicke in Logto auf **Speichern und Fertig**, um dein Identitätssystem mit GitHub zu verbinden. + +:::warning +Halte dein Client-Geheimnis sicher und gib es niemals im Client-seitigen Code preis. GitHub-Client-Geheimnisse können nicht wiederhergestellt werden, wenn sie verloren gehen – du musst ein neues generieren. +::: + +## Schritt 3: Berechtigungen (Scopes) konfigurieren (Optional) \{#step-3-configure-scopes-optional} + +Berechtigungen (Scopes) definieren, welche Zugriffsrechte deine App von den Benutzern anfordert und steuern, auf welche Daten deine App in deren GitHub-Konten zugreifen kann. + +Verwende das Feld `Scopes` in Logto, um zusätzliche Berechtigungen von GitHub anzufordern. Wähle je nach Bedarf eine der folgenden Vorgehensweisen: + +### Option 1: Keine zusätzlichen API-Berechtigungen benötigt \{#option-1-no-extra-api-scopes-needed} + +- Lasse das Feld `Scopes` in deinem Logto GitHub Connector leer. +- Die Standardberechtigung `read:user` wird angefordert, damit Logto grundlegende Benutzerinformationen (z. B. E-Mail, Name, Avatar) korrekt abrufen kann. -Wenn du die Fehlermeldung "The redirect_uri MUST match the registered callback URL for this application." beim Anmelden erhältst, versuche, die Authorization Callback URL deiner GitHub OAuth-App und die Redirect-URL deiner Logto-App (natürlich einschließlich des Protokolls) abzugleichen, um das Problem zu lösen. +### Option 2: Zusätzliche Berechtigungen beim Anmelden anfordern \{#option-2-request-additional-scopes-at-sign-in} +- Durchsuche alle verfügbaren [GitHub-Berechtigungen für OAuth-Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) und füge nur die Berechtigungen hinzu, die deine App benötigt. +- Gib alle gewünschten Berechtigungen im Feld **Scopes** ein, getrennt durch Leerzeichen. +- Alle hier aufgeführten Berechtigungen überschreiben die Standardwerte, daher immer die Authentifizierungsberechtigung `read:user` einschließen. +- Häufig verwendete zusätzliche Berechtigungen sind: + - `repo`: Vollständige Kontrolle über private Repositories + - `public_repo`: Zugriff auf öffentliche Repositories + - `user:email`: Zugriff auf Benutzer-E-Mail-Adressen + - `notifications`: Zugriff auf Benachrichtigungen +- Stelle sicher, dass alle Berechtigungen korrekt geschrieben und gültig sind. Eine falsche oder nicht unterstützte Berechtigung führt zu einem "Invalid scope"-Fehler von GitHub. + +### Option 3: Schrittweise Berechtigungen später anfordern \{#option-3-request-incremental-scopes-later} + +- Nachdem sich der Benutzer angemeldet hat, kannst du bei Bedarf zusätzliche Berechtigungen anfordern, indem du einen föderierten sozialen Autorisierungsfluss erneut initiierst und das gespeicherte Token-Set der Benutzer aktualisierst. +- Diese zusätzlichen Berechtigungen müssen nicht im Feld `Scopes` deines Logto GitHub Connectors eingetragen werden und können über die Social Verification API von Logto erreicht werden. + +Wenn du diese Schritte befolgst, fordert dein Logto GitHub Connector genau die Berechtigungen an, die deine App benötigt – nicht mehr und nicht weniger. + +:::tip +Wenn deine App diese Berechtigungen anfordert, um auf die GitHub API zuzugreifen und Aktionen auszuführen, stelle sicher, dass du **Tokens für dauerhaften API-Zugriff speichern** im Logto GitHub Connector aktivierst. Siehe den nächsten Abschnitt für Details. ::: -Wir empfehlen, das Kästchen vor **Enable Device Flow** nicht zu aktivieren, da Benutzer, die sich mit GitHub auf mobilen Geräten anmelden, die anfängliche Anmeldeaktion in der GitHub-App bestätigen müssen. Viele GitHub-Benutzer haben die GitHub-Mobile-App nicht auf ihren Telefonen installiert, was den Anmeldevorgang blockieren könnte. Bitte ignoriere unsere Empfehlung, wenn du erwartest, dass Endbenutzer ihren Anmeldevorgang bestätigen. Siehe Details zum [Device Flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). +## Schritt 4: Allgemeine Einstellungen \{#step-4-general-settings} + +Hier sind einige allgemeine Einstellungen, die die Verbindung zu GitHub nicht blockieren, aber das Authentifizierungserlebnis für Endbenutzer beeinflussen können. + +### Profilinformationen synchronisieren \{#sync-profile-information} -### Verwaltung von OAuth-Apps \{#managing-oauth-apps} +Im GitHub Connector kannst du die Richtlinie für das Synchronisieren von Profilinformationen wie Benutzernamen und Avataren festlegen. Wähle aus: -Gehe zur [OAuth-Apps-Seite](https://github.com/settings/developers), wo du vorhandene OAuth-Apps hinzufügen, bearbeiten oder löschen kannst. Du kannst auch `Client ID` finden und `Client secrets` auf den Detailseiten der OAuth-App generieren. +- **Nur bei Registrierung synchronisieren**: Profilinformationen werden einmalig abgerufen, wenn sich der Benutzer zum ersten Mal anmeldet. +- **Immer bei Anmeldung synchronisieren**: Profilinformationen werden jedes Mal aktualisiert, wenn sich der Benutzer anmeldet. -### Konfiguriere deinen Connector \{#configure-your-connector} +### Tokens speichern, um auf GitHub APIs zuzugreifen (Optional) \{#store-tokens-to-access-github-apis-optional} + +Wenn du auf GitHub APIs zugreifen und Aktionen mit Benutzerautorisierung durchführen möchtest (sei es über soziale Anmeldung oder Kontoverknüpfung), muss Logto bestimmte API-Berechtigungen erhalten und Tokens speichern. + +1. Füge die erforderlichen Berechtigungen gemäß den obigen Anweisungen hinzu. +2. Aktiviere **Tokens für dauerhaften API-Zugriff speichern** im Logto GitHub Connector. Logto speichert GitHub Zugangstokens sicher im Secret Vault. + +:::note +Wenn du eine GitHub **OAuth-App** wie in diesem Tutorial beschrieben verwendest, kannst du kein Auffrischungstoken (Refresh token) von GitHub erhalten, da dessen Zugangstoken (Access token) nicht abläuft, es sei denn, der Benutzer widerruft es manuell. Daher musst du `offline_access` nicht im Feld `Scopes` hinzufügen – dies könnte andernfalls zu einem Fehler führen. + +Wenn du möchtest, dass das Zugangstoken abläuft oder Auffrischungstokens verwendest, solltest du stattdessen die Integration mit einer **GitHub App** in Betracht ziehen. Erfahre mehr über die [Unterschiede zwischen GitHub Apps und OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). +::: -Fülle die Felder `clientId` und `clientSecret` mit der _Client ID_ und dem _Client Secret_ aus, die du auf den in der vorherigen Sektion erwähnten Detailseiten der OAuth-App erhalten hast. +## Schritt 5: Teste deine Integration (Optional) \{#step-5-test-your-integration-optional} -`scope` ist eine durch Leerzeichen getrennte Liste von [Berechtigungen (Scopes)](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). Wenn nicht angegeben, ist die Standardberechtigung `read:user`. +Bevor du live gehst, teste deine GitHub-Integration: -### Konfigurationstypen \{#config-types} +1. Verwende den Connector in einem Logto-Entwicklungstenant. +2. Überprüfe, ob sich Benutzer mit GitHub anmelden können. +3. Prüfe, ob die richtigen Berechtigungen angefordert werden. +4. Teste API-Aufrufe, wenn du Tokens speicherst. -| Name | Typ | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +GitHub OAuth-Apps funktionieren sofort mit jedem GitHub-Benutzerkonto – es sind keine Testbenutzer oder App-Freigaben wie bei anderen Plattformen erforderlich. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index 8898df5464d..e165862da40 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -2,24 +2,76 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: - description: Google ist ein führender Anbieter von Suchmaschinentechnologie und E-Mail-Diensten. -tutorial_config_name: Google OAuth-App + description: Google ist eine führende Suchmaschinentechnologie und Anbieter von E-Mail-Diensten. +tutorial_config_name: Google OAuth app --- import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Soziale Anmeldung mit Google einrichten +# Soziale Anmeldung mit Google einrichten (Set up social login with Google) -Der Google-Connector bietet eine prägnante Möglichkeit für deine Anwendung, das OAuth 2.0-Authentifizierungssystem von Google zu nutzen. +Integriere das Google OAuth 2.0-Authentifizierungssystem, um „Mit Google anmelden“, Kontoverknüpfung und sicheren Zugriff auf Google APIs zu ermöglichen. +## Loslegen \{#get-started} + +Der Google Connector ermöglicht die OAuth 2.0-Integration, damit deine Anwendung: + +- Die Authentifizierung „Mit Google anmelden“ hinzufügt +- Benutzerkonten mit Google-Identitäten verknüpft +- Benutzerprofilinformationen von Google synchronisiert +- Zugriff auf Google APIs durch sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben erhält (z. B. Bearbeiten von Google Docs, Verwalten von Kalenderereignissen in deiner App) + +Um diese Authentifizierungsfunktionen einzurichten, erstelle zuerst einen Google Connector in Logto: + +1. Gehe zu Logto-Konsole > Connector > Social Connector. +2. Klicke auf **Sozialen Connector hinzufügen**, wähle **Google**, klicke auf **Weiter** und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen. + -## Referenzen \{#references} +## Den Google Connector nutzen \{#utilize-the-google-connector} + +Nachdem du einen Google Connector erstellt und mit Google verbunden hast, kannst du ihn in deine Endbenutzer-Flows einbinden. Wähle die Optionen, die zu deinen Anforderungen passen: + +### „Mit Google anmelden“ aktivieren \{#enable-sign-in-with-google} + +1. Gehe in der Logto-Konsole zu Anmeldeerfahrung > Registrierung und Anmeldung. +2. Füge den Google Connector im Abschnitt **Soziale Anmeldung** hinzu, damit sich Benutzer mit Google authentifizieren können. +3. Aktiviere optional **Google One Tap** auf den Anmelde- und Registrierungsseiten für eine optimierte Authentifizierungserfahrung. + +Erfahre mehr über die [soziale Anmeldeerfahrung](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Ein Google-Konto verknüpfen oder trennen \{#link-or-unlink-a-google-account} + +Nutze die Account API, um ein benutzerdefiniertes Account Center in deiner App zu erstellen, das angemeldeten Benutzern ermöglicht, ihr Google-Konto zu verknüpfen oder zu trennen. [Folge dem Account API-Tutorial](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Es ist möglich, den Google Connector nur für die Kontoverknüpfung und den API-Zugriff zu aktivieren, ohne ihn für die soziale Anmeldung zu aktivieren. +::: + +### Auf Google APIs zugreifen und Aktionen ausführen \{#access-google-apis-and-perform-actions} + +Deine Anwendung kann gespeicherte Google Zugangstokens (Access tokens) aus dem Secret Vault abrufen, um Google APIs aufzurufen und Backend-Aufgaben zu automatisieren (zum Beispiel Google Drive-Dateien verwalten, Kalenderereignisse erstellen oder E-Mails über Gmail senden). Siehe die Anleitung zum Abrufen gespeicherter Tokens für den API-Zugriff. + +## Die Google-Identität des Benutzers verwalten \{#manage-user-s-google-identity} + +Nachdem ein Benutzer sein Google-Konto verknüpft hat, können Administratoren diese Verbindung in der Logto-Konsole verwalten: + +1. Navigiere zu Logto-Konsole > Benutzerverwaltung und öffne das Profil des Benutzers. +2. Unter **Soziale Verbindungen** finde den Google-Eintrag und klicke auf **Verwalten**. +3. Auf dieser Seite können Administratoren die Google-Verbindung des Benutzers verwalten, alle gewährten und von Google synchronisierten Profilinformationen einsehen und den Status des Zugangstokens (Access token) überprüfen. + +## Referenz \{#reference} - Google Identity: Einrichten von OAuth 2.0 + Google Identity: OAuth 2.0 einrichten + + + Google Identity Services (One Tap) + + +Google Cloud Console diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index 0caacf43a4b..d495580f5b6 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## Ein Projekt in der Google API Console einrichten \{#set-up-a-project-in-the-google-api-console} +## Schritt 1: Erstelle ein Projekt auf der Google Auth Platform \{#step-1-create-a-project-on-google-auth-platform} + +Bevor du Google als Authentifizierungsanbieter verwenden kannst, musst du ein Projekt in der Google Cloud Console einrichten, um OAuth 2.0-Zugangsdaten zu erhalten. Wenn du bereits ein Projekt hast, kannst du diesen Schritt überspringen. + +1. Besuche die [Google Cloud Console](https://console.cloud.google.com/) und melde dich mit deinem Google-Konto an. +2. Klicke auf die Schaltfläche **Projekt auswählen** in der oberen Menüleiste und dann auf **Neues Projekt**, um ein Projekt zu erstellen. +3. Navigiere in deinem neu erstellten Projekt zu **APIs & Dienste > OAuth-Zustimmungsbildschirm**, um deine App zu konfigurieren: + - **App-Informationen**: Gib den **Anwendungsnamen** und die **Support-E-Mail** ein, die auf der Zustimmungsseite angezeigt werden sollen. + - **Zielgruppe (Audience)**: Wähle deinen bevorzugten Zielgruppentyp: + - **Intern** – Nur für Google Workspace-Nutzer innerhalb deiner Organisation + - **Extern** – Für jeden Google-Nutzer (erfordert eine Überprüfung für den produktiven Einsatz) + - **Kontaktinformationen**: Gib E-Mail-Adressen an, damit Google dich über Änderungen an deinem Projekt benachrichtigen kann. + - Setze ein Häkchen bei **Ich stimme den Google-Richtlinien zu**, um die Grundeinrichtung abzuschließen. +4. Optional kannst du im Bereich **Branding** Produktinformationen bearbeiten und dein **App-Logo** hochladen, das auf dem OAuth-Zustimmungsbildschirm angezeigt wird, damit Nutzer deine App erkennen. + +:::tip +Wenn du den Zielgruppentyp **Extern** wählst, musst du während der Entwicklung Testnutzer hinzufügen und deine App für den produktiven Einsatz veröffentlichen. +::: + +## Schritt 2: Erstelle OAuth 2.0-Zugangsdaten \{#step-2-create-oauth-2-0-credentials} + +Navigiere zur [Zugangsdaten](https://console.cloud.google.com/apis/credentials)-Seite in der Google Cloud Console und erstelle OAuth-Zugangsdaten für deine Anwendung. + +1. Klicke auf **Zugangsdaten erstellen > OAuth-Client-ID**. +2. Wähle **Webanwendung** als Anwendungstyp. +3. Fülle den **Namen** deines OAuth-Clients aus. Dies hilft dir, die Zugangsdaten zu identifizieren und wird Endbenutzern nicht angezeigt. +4. Konfiguriere die autorisierten URIs: + - **Autorisierte JavaScript-Quellen**: Füge den Ursprung deiner Logto-Instanz hinzu (z. B. `https://your-logto-domain.com`) + - **Autorisierte Redirect-URIs**: Füge die Logto **Callback-URI** hinzu (kopiere diese aus deinem Logto Google Connector) +5. Klicke auf **Erstellen**, um den OAuth-Client zu generieren. + +## Schritt 3: Konfiguriere den Logto-Connector mit Zugangsdaten \{#step-3-configure-logto-connector-with-credentials} + +Nach dem Erstellen des OAuth-Clients zeigt Google ein Modal mit deinen Zugangsdaten an: + +1. Kopiere die **Client-ID** und füge sie in das Feld `clientId` in Logto ein. +2. Kopiere das **Client-Secret** und füge es in das Feld `clientSecret` in Logto ein. +3. Klicke auf **Speichern und Fertig** in Logto, um dein Identitätssystem mit Google zu verbinden. + +:::warning +Halte dein Client-Secret sicher und veröffentliche es niemals im Client-seitigen Code. Wenn es kompromittiert wird, generiere sofort ein neues. +::: + +## Schritt 4: Konfiguriere Berechtigungen (Scopes) \{#step-4-configure-scopes} + +Berechtigungen (Scopes) definieren, welche Zugriffsrechte deine App von den Nutzern anfordert und steuern, auf welche Daten deine App in deren Google-Konten zugreifen kann. + +### Berechtigungen in der Google Cloud Console konfigurieren \{#configure-scopes-in-google-cloud-console} + +1. Navigiere zu **APIs & Dienste > OAuth-Zustimmungsbildschirm > Berechtigungen (Scopes)**. +2. Klicke auf **Scopes hinzufügen oder entfernen** und wähle nur die Berechtigungen aus, die deine App benötigt: + - **Authentifizierung (erforderlich)**: + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **API-Zugriff (optional)**: Füge alle zusätzlichen Berechtigungen hinzu, die deine App benötigt (z. B. Drive, Kalender, YouTube). Durchsuche die [Google API-Bibliothek](https://console.cloud.google.com/apis/library), um verfügbare Dienste zu finden. Wenn deine App Zugriff auf Google APIs über die grundlegenden Berechtigungen hinaus benötigt, aktiviere zuerst die spezifischen APIs, die deine App verwenden wird (z. B. Google Drive API, Gmail API, Kalender API) in der Google API-Bibliothek. +3. Klicke auf **Aktualisieren**, um die Auswahl zu bestätigen. +4. Klicke auf **Speichern und Fortfahren**, um die Änderungen zu übernehmen. -- Besuche die [Google API Console](https://console.developers.google.com) und melde dich mit deinem Google-Konto an. -- Klicke auf die Schaltfläche **Projekt auswählen** in der oberen Menüleiste und klicke auf die Schaltfläche **Neues Projekt**, um ein Projekt zu erstellen. -- In deinem neu erstellten Projekt klicke auf **APIs & Services**, um das Menü **APIs & Services** zu öffnen. +### Berechtigungen in Logto konfigurieren \{#configure-scopes-in-logto} -## Deinen Zustimmungsbildschirm konfigurieren \{#configure-your-consent-screen} +Wähle je nach Bedarf eine oder mehrere der folgenden Vorgehensweisen: -### Deine Anwendung konfigurieren und registrieren \{#configure-and-register-your-application} +**Option 1: Keine zusätzlichen API-Berechtigungen benötigt** -- Klicke im linken Menü **APIs & Services** auf die Schaltfläche **OAuth-Zustimmungsbildschirm**. -- Wähle den gewünschten **Benutzertyp** aus und klicke auf die Schaltfläche **Erstellen**. (Hinweis: Wenn du **Extern** als **Benutzertyp** auswählst, musst du später Testbenutzer hinzufügen.) +- Lasse das Feld `Scopes` in deinem Logto Google Connector leer. +- Die Standardberechtigungen `openid profile email` werden angefordert, damit Logto grundlegende Benutzerinformationen korrekt abrufen kann. -Nun befindest du dich auf der Seite **App-Registrierung bearbeiten**. +**Option 2: Zusätzliche Berechtigungen beim Anmelden anfordern** -### App-Registrierung bearbeiten \{#edit-app-registration} +- Gib alle gewünschten Berechtigungen im Feld **Scopes** ein, getrennt durch Leerzeichen. +- Alle hier aufgeführten Berechtigungen überschreiben die Standardwerte, daher immer die Authentifizierungs-Berechtigungen einfügen: `https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`. +- Verwende vollständige Scope-URLs. Beispiel: `https://www.googleapis.com/auth/calendar.readonly`. -#### OAuth-Zustimmungsbildschirm konfigurieren \{#config-oauth-consent-screen} +**Option 3: Zusätzliche Berechtigungen später inkrementell anfordern** -- Folge den Anweisungen, um das Formular **OAuth-Zustimmungsbildschirm** auszufüllen. -- Klicke auf **SPEICHERN UND FORTFAHREN**, um fortzufahren. +- Nachdem sich der Nutzer angemeldet hat, kannst du bei Bedarf zusätzliche Berechtigungen anfordern, indem du einen föderierten sozialen Autorisierungsfluss erneut initiierst und das gespeicherte Token-Set des Nutzers aktualisierst. +- Diese zusätzlichen Berechtigungen müssen nicht im Feld `Scopes` deines Logto Google Connectors eingetragen werden und können über die Social Verification API von Logto erreicht werden. -#### Berechtigungen konfigurieren \{#config-scopes} +Wenn du diese Schritte befolgst, fordert dein Logto Google Connector genau die Berechtigungen an, die deine App benötigt – nicht mehr und nicht weniger. -- Klicke auf **BERECHTIGUNGEN HINZUFÜGEN ODER ENTFERNEN** und wähle `../auth/userinfo.email`, `../auth/userinfo.profile` und `openid` im Popup-Fenster aus und klicke auf **AKTUALISIEREN**, um abzuschließen. Es wird empfohlen, alle Berechtigungen hinzuzufügen, die du möglicherweise verwendest, da sonst einige Berechtigungen, die du in der Konfiguration hinzugefügt hast, möglicherweise nicht funktionieren. -- Fülle das Formular nach Bedarf aus. -- Klicke auf **SPEICHERN UND FORTFAHREN**, um fortzufahren. +:::tip +Wenn deine App diese Berechtigungen anfordert, um auf die Google API zuzugreifen und Aktionen auszuführen, stelle sicher, dass du **Tokens für dauerhaften API-Zugriff speichern** im Logto Google Connector aktivierst. Siehe den nächsten Abschnitt für Details. +::: -#### Testbenutzer hinzufügen (nur externer Benutzertyp) \{#add-test-users-external-user-type-only} +## Schritt 5: Authentifizierungsaufforderungen anpassen \{#step-5-customize-authentication-prompts} -- Klicke auf **BENUTZER HINZUFÜGEN** und füge Testbenutzer hinzu, um diesen Benutzern den Zugriff auf deine Anwendung während des Testens zu ermöglichen. -- Klicke auf **SPEICHERN UND FORTFAHREN**, um fortzufahren. +Konfiguriere **Prompts** in Logto, um die Benutzererfahrung bei der Authentifizierung zu steuern. Prompts ist ein Array von Zeichenfolgen, das die Art der erforderlichen Benutzerinteraktion angibt: -Nun solltest du den Google OAuth 2.0-Zustimmungsbildschirm konfiguriert haben. +- `none` – Der Autorisierungsserver zeigt keine Authentifizierungs- oder Zustimmungsbildschirme an. Gibt einen Fehler zurück, wenn der Nutzer noch nicht authentifiziert ist und keine vorherige Zustimmung für die angeforderten Berechtigungen erteilt hat. Verwende dies, um auf bestehende Authentifizierung und/oder Zustimmung zu prüfen. +- `consent` – Der Autorisierungsserver fordert den Nutzer zur Zustimmung auf, bevor Informationen an den Client zurückgegeben werden. Erforderlich, um **Offline-Zugriff** für den Google API-Zugriff zu aktivieren. +- `select_account` – Der Autorisierungsserver fordert den Nutzer auf, ein Benutzerkonto auszuwählen. Dies ermöglicht Nutzern mit mehreren Google-Konten, das gewünschte Konto für die Authentifizierung auszuwählen. -## OAuth 2.0-Anmeldedaten erhalten \{#obtain-oauth-20-credentials} +## Schritt 6: Allgemeine Einstellungen \{#step-6-general-settings} -- Klicke im linken Menü **APIs & Services** auf die Schaltfläche **Anmeldedaten**. -- Auf der Seite **Anmeldedaten** klicke auf die Schaltfläche **+ ANMELDEDATEN ERSTELLEN** in der oberen Menüleiste und wähle **OAuth-Client-ID** aus. -- Auf der Seite **OAuth-Client-ID erstellen** wähle **Webanwendung** als Anwendungstyp aus. -- Fülle die grundlegenden Informationen für deine Anwendung aus. -- Klicke auf **+ URI hinzufügen**, um eine autorisierte Domain im Abschnitt **Autorisierte JavaScript-Ursprünge** hinzuzufügen. Dies ist die Domain, von der deine Logto-Autorisierungsseite bereitgestellt wird. In unserem Fall wird dies `${your_logto_origin}` sein, z. B. `https://logto.dev`. -- Klicke auf **+ URI hinzufügen** im Abschnitt **Autorisierte Weiterleitungs-URIs**, um die **Autorisierte Weiterleitungs-URIs** einzurichten, die den Benutzer nach der Anmeldung zur Anwendung weiterleiten. In unserem Fall wird dies `${your_logto_endpoint}/callback/${connector_id}` sein, z. B. `https://logto.dev/callback/${connector_id}`. Die `connector_id` findest du in der oberen Leiste der Logto Admin Console Connector-Detailseite. -- Klicke auf **Erstellen**, um abzuschließen, und dann erhältst du die **Client-ID** und das **Client Secret**. +Hier sind einige allgemeine Einstellungen, die die Verbindung zu Google nicht blockieren, aber die Authentifizierungserfahrung der Endnutzer beeinflussen können. -## Deinen Connector konfigurieren \{#configure-your-connector} +### Profilinformationen synchronisieren \{#sync-profile-information} -Fülle die Felder `clientId` und `clientSecret` mit der _Client-ID_ und dem _Client Secret_ aus, die du von den OAuth-App-Detailseiten im vorherigen Abschnitt erhalten hast. +Im Google Connector kannst du die Richtlinie für das Synchronisieren von Profilinformationen wie Benutzernamen und Avataren festlegen. Wähle aus: -`scope` ist eine durch Leerzeichen getrennte Liste von [Berechtigungen](https://developers.google.com/identity/protocols/oauth2/scopes). Wenn nicht angegeben, ist die Standardberechtigung `openid profile email`. +- **Nur bei Registrierung synchronisieren**: Profilinformationen werden einmalig abgerufen, wenn sich der Nutzer zum ersten Mal anmeldet. +- **Immer bei Anmeldung synchronisieren**: Profilinformationen werden jedes Mal aktualisiert, wenn sich der Nutzer anmeldet. -`prompts` ist ein Array von Zeichenfolgen, das den erforderlichen Benutzereingriffstyp angibt. Die Zeichenfolge kann einen der folgenden Werte haben: +### Tokens speichern, um auf Google APIs zuzugreifen (Optional) \{#store-tokens-to-access-google-apis-optional} -- `none`: Der Autorisierungsserver zeigt keine Authentifizierungs- oder Benutzerzustimmungsbildschirme an; er gibt einen Fehler zurück, wenn der Benutzer nicht bereits authentifiziert ist und keine vorherige Zustimmung für die angeforderten Berechtigungen konfiguriert hat. Du kannst `none` verwenden, um auf bestehende Authentifizierung und / oder Zustimmung zu prüfen. -- `consent`: Der Autorisierungsserver fordert den Benutzer zur Zustimmung auf, bevor er Informationen an den Client zurückgibt. -- `select_account`: Der Autorisierungsserver fordert den Benutzer auf, ein Benutzerkonto auszuwählen. Dies ermöglicht einem Benutzer, der mehrere Konten beim Autorisierungsserver hat, die Auswahl zwischen den mehreren Konten, für die er aktuelle Sitzungen haben kann. +Wenn du auf [Google APIs](https://console.cloud.google.com/apis/library) zugreifen und Aktionen mit Nutzerautorisierung durchführen möchtest (egal ob über soziale Anmeldung oder Kontoverknüpfung), muss Logto bestimmte API-Berechtigungen erhalten und Tokens speichern. -### Konfigurationstypen \{#config-types} +1. Füge die erforderlichen Berechtigungen in deiner Google Cloud Console OAuth-Zustimmungsbildschirm-Konfiguration und im Logto Google Connector hinzu. +2. Aktiviere **Tokens für dauerhaften API-Zugriff speichern** im Logto Google Connector. Logto speichert Google-Zugangs- und Auffrischungstokens sicher im Secret Vault. +3. Um sicherzustellen, dass Auffrischungstokens zurückgegeben werden, konfiguriere deinen Logto Google Connector wie folgt: + - Setze **Prompts** so, dass `consent` enthalten ist. + - Aktiviere **Offline-Zugriff**. -| Name | Typ | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +Du musst `offline_access` nicht im Logto `Scope`-Feld hinzufügen – dies kann zu einem Fehler führen. Google verwendet automatisch `access_type=offline`, wenn Offline-Zugriff aktiviert ist. +::: -## Google One Tap aktivieren \{#enable-google-one-tap} +## Schritt 7: Google One Tap aktivieren (Optional) \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) ist eine sichere und einfache Möglichkeit, Benutzern die Anmeldung auf deiner Website oder App mit ihrem Google-Konto zu ermöglichen. +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) ist eine sichere und unkomplizierte Möglichkeit, Nutzern die Anmeldung auf deiner Website mit ihrem Google-Konto über eine Popup-Oberfläche zu ermöglichen. -Sobald du den Google-Connector eingerichtet hast, siehst du eine Karte für Google One Tap auf der Connector-Detailseite. Du kannst Google One Tap auf deinen Anmelde- und Registrierungsseiten aktivieren, indem du den Schalter umlegst. +Sobald du den Google Connector eingerichtet hast, siehst du eine Karte für Google One Tap auf der Connector-Detailseite. Aktiviere Google One Tap, indem du den Schalter umlegst. -Wenn du Google One Tap aktivierst, kannst du die folgenden Optionen konfigurieren: +### Google One Tap Konfigurationsoptionen \{#google-one-tap-configuration-options} -- **Anmeldedaten automatisch auswählen, wenn möglich**: Melde den Benutzer automatisch mit dem Google-Konto an, wenn [bestimmte Bedingungen erfüllt sind](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out). -- **Aufforderung abbrechen, wenn der Benutzer außerhalb klickt / tippt**: Schließe die Google One Tap-Aufforderung, wenn der Benutzer außerhalb der Aufforderung klickt oder tippt. Wenn deaktiviert, muss der Benutzer auf die Schaltfläche zum Schließen klicken, um die Aufforderung zu schließen. -- **Aktualisierte One Tap UX auf ITP-Browsern aktivieren**: Aktiviere die aktualisierte Google One Tap-Benutzererfahrung auf Intelligent Tracking Prevention (ITP)-Browsern. Bitte siehe [diese Seite](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) für weitere Informationen. +- **Anmeldedaten automatisch auswählen, wenn möglich** – Melde den Nutzer automatisch mit dem Google-Konto an, wenn [bestimmte Bedingungen erfüllt sind](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out). +- **Aufforderung abbrechen, wenn der Nutzer außerhalb klickt/tippt** – Schließe die Google One Tap-Aufforderung, wenn der Nutzer außerhalb des Prompts klickt oder tippt. Wenn deaktiviert, muss der Nutzer auf die Schaltfläche „Schließen“ klicken, um die Aufforderung zu schließen. +- **Verbesserte One Tap UX auf ITP-Browsern aktivieren** – Aktiviere die verbesserte Google One Tap-Benutzererfahrung auf Intelligent Tracking Prevention (ITP)-Browsern. Weitere Informationen findest du in [dieser Dokumentation](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers). -:::caution -Stelle sicher, dass du deinen Server-Ursprung im Abschnitt **Autorisierte JavaScript-Ursprünge** in der OAuth-Zustimmungsbildschirmkonfiguration hinzufügst. Andernfalls kann Google One Tap nicht angezeigt werden. +:::warning +Stelle sicher, dass du deine Domain im Abschnitt **Autorisierte JavaScript-Quellen** deiner OAuth-Client-Konfiguration hinzufügst. Andernfalls kann Google One Tap nicht angezeigt werden. ::: +### Wichtige Einschränkungen bei Google One Tap \{#important-limitations-with-google-one-tap} + +Wenn du **Tokens für dauerhaften API-Zugriff speichern** zusammen mit **Google One Tap** aktivierst, erhältst du nicht automatisch ein Zugangstoken oder die angeforderten Berechtigungen. + +Die Google One Tap-Anmeldung (im Gegensatz zum Standard-Button „Mit Google anmelden“) stellt **kein** OAuth-Zugangstoken aus. Sie gibt nur ein ID-Token (ein signiertes JWT) zurück, das die Identität des Nutzers bestätigt, aber keinen API-Zugriff gewährt. + +Um mit Google One Tap-Nutzern auf Google APIs zuzugreifen, kannst du die Social Verification API von Logto verwenden, um nach der Anmeldung mit Google One Tap einen föderierten sozialen Autorisierungsfluss erneut zu initiieren. So kannst du bei Bedarf zusätzliche Berechtigungen anfordern und das gespeicherte Token-Set des Nutzers aktualisieren, ohne dass die Berechtigungen im Logto Google Connector vorab eingetragen werden müssen. Dieser Ansatz ermöglicht eine inkrementelle Autorisierung, sodass Nutzer nur dann um zusätzliche Berechtigungen gebeten werden, wenn deine App sie tatsächlich benötigt. + +Weitere Informationen zu [Google One Tap-Einschränkungen](https://developers.google.com/identity/gsi/web/guides/overview) findest du in der offiziellen Dokumentation. + +## Schritt 8: Teste und veröffentliche deine App \{#step-8-test-and-publish-your-app} + +### Für interne Apps \{#for-internal-apps} + +Wenn dein **Zielgruppen**-Typ in Google auf **Intern** gesetzt ist, steht deine App nur Google Workspace-Nutzern innerhalb deiner Organisation zur Verfügung. Du kannst mit jedem Konto aus deiner Organisation testen. + +### Für externe Apps \{#for-external-apps} + +Wenn dein **Zielgruppen**-Typ **Extern** ist: + +1. **Während der Entwicklung**: Navigiere zu **OAuth-Zustimmungsbildschirm > Testnutzer** und füge die E-Mail-Adressen der Testnutzer hinzu. Nur diese Nutzer können sich mit deiner App anmelden. +2. **Für den produktiven Einsatz**: Klicke im Bereich OAuth-Zustimmungsbildschirm auf **App veröffentlichen**, um sie für alle mit einem Google-Konto verfügbar zu machen. + :::note -Um Google One Tap auf deiner Website (über die Logto-Anmeldeerfahrung hinaus) zu aktivieren, befindet sich diese Funktion in der Entwicklung. Bitte bleibe für Updates dran. +Apps mit sensiblen oder eingeschränkten Berechtigungen müssen möglicherweise von Google überprüft werden, bevor sie veröffentlicht werden können. Dieser Prozess kann mehrere Wochen dauern. ::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index 71c0d728ed6..802a2de4b15 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -2,17 +2,17 @@ slug: /integrations/oauth2 sidebar_label: OAuth 2.0 (Sozial) sidebar_custom_props: - description: Das OAuth 2.0 Autorisierungsframework ermöglicht einer Drittanbieteranwendung, eingeschränkten Zugriff auf einen HTTP-Dienst zu erhalten. + description: Das OAuth 2.0 Autorisierungs-Framework ermöglicht es einer Drittanbieteranwendung, einen eingeschränkten Zugriff auf einen HTTP-Dienst zu erhalten. logoFilename: 'oauth.svg' tutorial_name: OAuth2 -tutorial_config_name: Standard OAuth 2.0 App +tutorial_config_name: Standard OAuth 2.0 app --- import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Soziale Anmeldung mit OAuth 2.0-Protokoll einrichten +# Soziale Anmeldung mit OAuth 2.0-Protokoll einrichten (Set up social login with OAuth 2.0 protocol) Der offizielle Logto Connector für das OAuth 2.0-Protokoll. @@ -20,11 +20,21 @@ Der offizielle Logto Connector für das OAuth 2.0-Protokoll. ## Erste Schritte \{#get-started} -Der OAuth Connector ermöglicht Logtos Verbindung zu einem beliebigen sozialen Identitätsanbieter, der das OAuth 2.0-Protokoll unterstützt. +Der OAuth Connector ermöglicht die Verbindung von Logto zu einem beliebigen sozialen Identitätsanbieter, der das OAuth 2.0-Protokoll unterstützt. Verwende den OAuth Connector, um deiner Anwendung zu ermöglichen: + +- Soziale Anmeldebuttons hinzuzufügen +- Benutzerkonten mit sozialen Identitäten zu verknüpfen +- Benutzerprofilinformationen vom sozialen Anbieter zu synchronisieren +- Zugriff auf Drittanbieter-APIs durch sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben (z. B. Bearbeiten von Google Docs, Verwalten von Kalenderereignissen in deiner App) + +Um diese Authentifizierungsfunktionen einzurichten, erstelle zuerst einen OAuth 2.0 Connector in Logto: + +1. Gehe zu Logto-Konsole > Connector > Sozialer Connector. +2. Klicke auf **Sozialen Connector hinzufügen**, wähle **OAuth 2.0**, klicke auf **Weiter** und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen. :::note -Der OAuth Connector ist eine spezielle Art von Connector in Logto, du kannst einige auf dem OAuth-Protokoll basierende Connectors hinzufügen. +Der OAuth Connector ist eine besondere Art von Connector in Logto, du kannst mehrere auf dem OAuth-Protokoll basierende Connectoren hinzufügen. ::: @@ -32,4 +42,4 @@ Der OAuth Connector ist eine spezielle Art von Connector in Logto, du kannst ein ## Referenz \{#reference} -Das OAuth 2.0 Autorisierungsframework +Das OAuth 2.0 Autorisierungs-Framework diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index 2a9a3f81ae6..73e30c7c94a 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ ## Erstelle deine OAuth-App \{#create-your-oauth-app} -Wenn du diese Seite öffnest, gehen wir davon aus, dass du bereits weißt, mit welchem sozialen Identitätsanbieter du dich verbinden möchtest. Das Erste, was zu tun ist, ist zu bestätigen, dass der Identitätsanbieter das OAuth-Protokoll unterstützt, da dies eine Voraussetzung für die Konfiguration eines gültigen Connectors ist. Folge dann den Anweisungen des Identitätsanbieters, um die relevante App für die OAuth-Autorisierung zu registrieren und zu erstellen. +Wenn du diese Seite öffnest, gehen wir davon aus, dass du bereits weißt, mit welchem sozialen Identitätsanbieter du dich verbinden möchtest. Das Erste, was du tun solltest, ist zu bestätigen, dass der Identitätsanbieter das OAuth-Protokoll unterstützt, da dies eine Voraussetzung für die Konfiguration eines gültigen Connectors ist. Folge dann den Anweisungen des Identitätsanbieters, um die entsprechende App für die OAuth-Autorisierung zu registrieren und zu erstellen. ## Konfiguriere deinen Connector \{#configure-your-connector} -Wir unterstützen aus Sicherheitsgründen NUR den "Authorization Code"-Grant-Typ, und er passt perfekt zu Logtos Szenario. +Wir unterstützen AUSSCHLIESSLICH den "Authorization Code" Grant-Typ aus Sicherheitsgründen, und dieser passt perfekt zum Szenario von Logto. -`clientId` und `clientSecret` findest du auf der Detailseite deiner OAuth-Apps. +`clientId` und `clientSecret` findest du auf der Detailseite deiner OAuth-App. -_clientId_: Die Client-ID ist ein eindeutiger Bezeichner, der die Client-Anwendung während der Registrierung beim Autorisierungsserver identifiziert. Diese ID wird vom Autorisierungsserver verwendet, um die Identität der Client-Anwendung zu überprüfen und alle autorisierten Zugangstokens mit dieser spezifischen Client-Anwendung zu verknüpfen. +_clientId_: Die Client-ID ist ein eindeutiger Bezeichner, der die Client-Anwendung während der Registrierung beim Aussteller (Issuer) identifiziert. Diese ID wird vom Aussteller verwendet, um die Identität der Client-Anwendung zu überprüfen und alle autorisierten Zugangstokens mit dieser spezifischen Client-Anwendung zu verknüpfen. -_clientSecret_: Das Client-Secret ist ein vertraulicher Schlüssel, der der Client-Anwendung vom Autorisierungsserver während der Registrierung ausgestellt wird. Die Client-Anwendung verwendet diesen geheimen Schlüssel, um sich beim Autorisierungsserver zu authentifizieren, wenn sie Zugangstokens anfordert. Das Client-Secret wird als vertrauliche Information betrachtet und sollte jederzeit sicher aufbewahrt werden. +_clientSecret_: Das Client-Secret ist ein vertraulicher Schlüssel, der der Client-Anwendung vom Aussteller während der Registrierung ausgestellt wird. Die Client-Anwendung verwendet diesen geheimen Schlüssel, um sich beim Aussteller zu authentifizieren, wenn Zugangstokens angefordert werden. Das Client-Secret gilt als vertrauliche Information und sollte stets sicher aufbewahrt werden. -_tokenEndpointAuthMethod_: Die Authentifizierungsmethode des Token-Endpunkts wird von der Client-Anwendung verwendet, um sich beim Autorisierungsserver zu authentifizieren, wenn sie Zugangstokens anfordert. Um unterstützte Methoden zu entdecken, konsultiere das Feld `token_endpoint_auth_methods_supported`, das am OpenID Connect Discovery-Endpunkt des OAuth 2.0-Dienstanbieters verfügbar ist, oder beziehe dich auf die relevante Dokumentation des OAuth 2.0-Dienstanbieters. +_tokenEndpointAuthMethod_: Die Authentifizierungsmethode für den Token-Endpunkt wird von der Client-Anwendung verwendet, um sich beim Aussteller zu authentifizieren, wenn Zugangstokens angefordert werden. Um unterstützte Methoden zu entdecken, konsultiere das Feld `token_endpoint_auth_methods_supported`, das am OpenID Connect Discovery-Endpunkt des OAuth 2.0-Dienstanbieters verfügbar ist, oder schaue in die entsprechende Dokumentation des OAuth 2.0-Dienstanbieters. -_clientSecretJwtSigningAlgorithm (Optional)_: Nur erforderlich, wenn `tokenEndpointAuthMethod` `client_secret_jwt` ist. Der Client-Secret-JWT-Signaturalgorithmus wird von der Client-Anwendung verwendet, um das JWT zu signieren, das während der Token-Anfrage an den Autorisierungsserver gesendet wird. +_clientSecretJwtSigningAlgorithm (Optional)_: Nur erforderlich, wenn `tokenEndpointAuthMethod` auf `client_secret_jwt` gesetzt ist. Der Client-Secret-JWT-Signaturalgorithmus wird von der Client-Anwendung verwendet, um das JWT zu signieren, das während der Token-Anfrage an den Aussteller gesendet wird. -_scope_: Der Scope-Parameter wird verwendet, um die Menge der Ressourcen und Berechtigungen anzugeben, auf die die Client-Anwendung zugreifen möchte. Der Scope-Parameter wird typischerweise als durch Leerzeichen getrennte Liste von Werten definiert, die spezifische Berechtigungen darstellen. Zum Beispiel könnte ein Scope-Wert von "read write" anzeigen, dass die Client-Anwendung Lese- und Schreibzugriff auf die Daten eines Benutzers anfordert. +_scope_: Der Scope-Parameter wird verwendet, um die Menge an Ressourcen und Berechtigungen (Scopes) anzugeben, auf die die Client-Anwendung zugreifen möchte. Der Scope-Parameter wird typischerweise als durch Leerzeichen getrennte Liste von Werten definiert, die bestimmte Berechtigungen darstellen. Zum Beispiel könnte ein Scope-Wert von "read write" anzeigen, dass die Client-Anwendung Lese- und Schreibzugriff auf die Daten eines Benutzers anfordert. Du solltest `authorizationEndpoint`, `tokenEndpoint` und `userInfoEndpoint` in der Dokumentation des sozialen Anbieters finden. -_authenticationEndpoint_: Dieser Endpunkt wird verwendet, um den Authentifizierungsprozess zu initiieren. Der Authentifizierungsprozess beinhaltet typischerweise, dass sich der Benutzer anmeldet und der Client-Anwendung die Berechtigung erteilt, auf seine Ressourcen zuzugreifen. +_authenticationEndpoint_: Dieser Endpunkt wird verwendet, um den Authentifizierungsprozess zu starten. Der Authentifizierungsprozess beinhaltet typischerweise, dass sich der Benutzer anmeldet und der Client-Anwendung die Autorisierung erteilt, auf seine Ressourcen zuzugreifen. -_tokenEndpoint_: Dieser Endpunkt wird von der Client-Anwendung verwendet, um ein Zugangstoken zu erhalten, das zum Zugriff auf die angeforderten Ressourcen verwendet werden kann. Die Client-Anwendung sendet typischerweise eine Anfrage an den Token-Endpunkt mit einem Grant-Typ und einem Autorisierungscode, um ein Zugangstoken zu erhalten. +_tokenEndpoint_: Dieser Endpunkt wird von der Client-Anwendung verwendet, um ein Zugangstoken zu erhalten, das zum Zugriff auf die angeforderten Ressourcen verwendet werden kann. Die Client-Anwendung sendet typischerweise eine Anfrage mit einem Grant-Typ und einem Autorisierungscode an den Token-Endpunkt, um ein Zugangstoken zu erhalten. -_userInfoEndpoint_: Dieser Endpunkt wird von der Client-Anwendung verwendet, um zusätzliche Informationen über den Benutzer zu erhalten, wie z. B. seinen vollständigen Namen, seine E-Mail-Adresse oder sein Profilbild. Der Benutzerinfo-Endpunkt wird typischerweise aufgerufen, nachdem die Client-Anwendung ein Zugangstoken vom Token-Endpunkt erhalten hat. +_userInfoEndpoint_: Dieser Endpunkt wird von der Client-Anwendung verwendet, um zusätzliche Informationen über den Benutzer zu erhalten, wie z. B. seinen vollständigen Namen, seine E-Mail-Adresse oder sein Profilbild. Der User-Info-Endpunkt wird typischerweise aufgerufen, nachdem die Client-Anwendung ein Zugangstoken vom Token-Endpunkt erhalten hat. -Logto bietet auch ein `profileMap`-Feld, mit dem Benutzer die Zuordnung von den Profilen der sozialen Anbieter, die normalerweise nicht standardisiert sind, anpassen können. Die Schlüssel sind Logtos standardisierte Benutzerprofil-Feldnamen und die entsprechenden Werte sollten die Feldnamen der sozialen Profile sein. In der aktuellen Phase interessiert sich Logto nur für 'id', 'name', 'avatar', 'email' und 'phone' aus dem sozialen Profil, wobei nur 'id' erforderlich ist und die anderen optionale Felder sind. +Logto stellt außerdem ein `profileMap`-Feld bereit, mit dem Benutzer die Zuordnung von Profilfeldern der sozialen Anbieter anpassen können, da diese oft nicht standardisiert sind. Die Schlüssel sind die standardisierten Benutzprofil-Feldnamen von Logto, und die entsprechenden Werte sollten die Feldnamen der sozialen Profile sein. Im aktuellen Stadium berücksichtigt Logto nur 'id', 'name', 'avatar', 'email' und 'phone' aus dem sozialen Profil, wobei nur 'id' erforderlich ist und die anderen Felder optional sind. -`responseType` und `grantType` können NUR feste Werte mit dem Authorization Code Grant-Typ sein, daher machen wir sie optional und Standardwerte werden automatisch ausgefüllt. +`responseType` und `grantType` können NUR FESTE Werte mit dem Authorization Code Grant-Typ sein, daher machen wir sie optional und Standardwerte werden automatisch ausgefüllt. -Zum Beispiel kannst du [Google Benutzerprofilantwort](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) finden und daher sollte sein `profileMap` so aussehen: +Zum Beispiel findest du [Google User Profile Response](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) und daher sollte das `profileMap` wie folgt aussehen: ```json { @@ -41,8 +41,8 @@ Zum Beispiel kannst du [Google Benutzerprofilantwort](https://developers.google. :::note -Wir haben einen OPTIONALEN `customConfig`-Schlüssel bereitgestellt, um deine angepassten Parameter zu platzieren. -Jeder soziale Identitätsanbieter könnte seine eigene Variante des OAuth-Standardprotokolls haben. Wenn dein gewünschter sozialer Identitätsanbieter strikt am OAuth-Standardprotokoll festhält, musst du dich nicht um `customConfig` kümmern. +Wir haben einen OPTIONALEN Schlüssel `customConfig` bereitgestellt, um deine eigenen Parameter einzufügen. +Jeder soziale Identitätsanbieter kann seine eigene Variante des OAuth-Standardprotokolls haben. Wenn dein gewünschter sozialer Identitätsanbieter strikt dem OAuth-Standardprotokoll folgt, musst du dich nicht um `customConfig` kümmern. ::: @@ -50,22 +50,88 @@ Jeder soziale Identitätsanbieter könnte seine eigene Variante des OAuth-Standa | Name | Typ | Erforderlich | | ------------------------- | ----------------------- | ------------ | -| authorizationEndpoint | string | true | -| userInfoEndpoint | string | true | -| clientId | string | true | -| clientSecret | string | true | -| tokenEndpointResponseType | enum | false | -| responseType | string | false | -| grantType | string | false | -| tokenEndpoint | string | false | -| scope | string | false | -| customConfig | Record\ | false | -| profileMap | ProfileMap | false | +| authorizationEndpoint | string | ja | +| userInfoEndpoint | string | ja | +| clientId | string | ja | +| clientSecret | string | ja | +| tokenEndpointResponseType | enum | nein | +| responseType | string | nein | +| grantType | string | nein | +| tokenEndpoint | string | nein | +| scope | string | nein | +| customConfig | Record\ | nein | +| profileMap | ProfileMap | nein | | ProfileMap-Felder | Typ | Erforderlich | Standardwert | | ----------------- | ------ | ------------ | ------------ | -| id | string | false | id | -| name | string | false | name | -| avatar | string | false | avatar | -| email | string | false | email | -| phone | string | false | phone | +| id | string | nein | id | +| name | string | nein | name | +| avatar | string | nein | avatar | +| email | string | nein | email | +| phone | string | nein | phone | + +## Allgemeine Einstellungen \{#general-settings} + +Hier sind einige allgemeine Einstellungen, die die Verbindung zu deinem Identitätsanbieter nicht blockieren, aber die Authentifizierungserfahrung für Endbenutzer beeinflussen können. + +### Name und Logo des sozialen Buttons \{#social-button-name-and-logo} + +Wenn du einen sozialen Button auf deiner Anmeldeseite anzeigen möchtest, kannst du den **Namen** und das **Logo** (Dark Mode und Light Mode) des sozialen Identitätsanbieters festlegen. Dies hilft den Benutzern, die Option für die soziale Anmeldung zu erkennen. + +### Name des Identitätsanbieters \{#identity-provider-name} + +Jeder Social Connector hat einen eindeutigen Identitätsanbieter (IdP)-Namen, um Benutzeridentitäten zu unterscheiden. Während gängige Connectoren einen festen IdP-Namen verwenden, benötigen benutzerdefinierte Connectoren einen eindeutigen Wert. Erfahre mehr über [IdP-Namen](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) für weitere Details. + +### Profilinformationen synchronisieren \{#sync-profile-information} + +Im OAuth-Connector kannst du die Richtlinie für das Synchronisieren von Profilinformationen wie Benutzernamen und Avataren festlegen. Wähle aus: + +- **Nur beim ersten Anmelden synchronisieren**: Profilinformationen werden einmalig abgerufen, wenn sich der Benutzer zum ersten Mal anmeldet. +- **Immer beim Anmelden synchronisieren**: Profilinformationen werden jedes Mal aktualisiert, wenn sich der Benutzer anmeldet. + +### Tokens speichern, um auf Drittanbieter-APIs zuzugreifen (Optional) \{#store-tokens-to-access-third-party-apis-optional} + +Wenn du auf die APIs des Identitätsanbieters zugreifen und Aktionen mit Benutzerautorisierung durchführen möchtest (entweder über soziale Anmeldung oder Kontoverknüpfung), muss Logto bestimmte API-Berechtigungen (Scopes) erhalten und Tokens speichern. + +1. Füge die erforderlichen Scopes im **scope**-Feld gemäß den obigen Anweisungen hinzu. +2. Aktiviere **Tokens für dauerhaften API-Zugriff speichern** im Logto OAuth-Connector. Logto speichert Zugangstokens sicher im Secret Vault. +3. Für **Standard** OAuth/OIDC-Identitätsanbieter muss der Scope `offline_access` enthalten sein, um ein Auffrischungstoken (Refresh token) zu erhalten und wiederholte Benutzerzustimmungsaufforderungen zu vermeiden. + +:::warning +Halte dein Client-Secret sicher und veröffentliche es niemals im Client-seitigen Code. Wenn es kompromittiert wird, generiere sofort ein neues in den App-Einstellungen deines Identitätsanbieters. +::: + +## Den OAuth-Connector nutzen \{#utilize-the-oauth-connector} + +Sobald du einen OAuth-Connector erstellt und mit deinem Identitätsanbieter verbunden hast, kannst du ihn in deine Endbenutzer-Flows einbinden. Wähle die Optionen, die zu deinen Anforderungen passen: + +### Social Sign-in-Button aktivieren \{#enable-social-sign-in-button} + +1. Gehe in der Logto Console zu Anmeldeerfahrung > Registrierung und Anmeldung. +2. Füge den OAuth-Connector im Abschnitt **Soziale Anmeldung** hinzu, damit Benutzer sich mit deinem Identitätsanbieter authentifizieren können. + +Erfahre mehr über die [soziale Anmeldeerfahrung](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Ein soziales Konto verknüpfen oder trennen \{#link-or-unlink-a-social-account} + +Nutze die Account API, um ein benutzerdefiniertes Account Center in deiner App zu erstellen, das angemeldeten Benutzern ermöglicht, ihre sozialen Konten zu verknüpfen oder zu trennen. [Folge dem Account API-Tutorial](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Es ist erlaubt, den OAuth-Connector nur für Kontoverknüpfung und API-Zugriff zu aktivieren, ohne ihn für die soziale Anmeldung zu aktivieren. +::: + +### Auf Identitätsanbieter-APIs zugreifen und Aktionen durchführen \{#access-identity-provider-apis-and-perform-actions} + +Deine Anwendung kann gespeicherte Zugangstokens aus dem Secret Vault abrufen, um die APIs deines Identitätsanbieters aufzurufen und Backend-Aufgaben zu automatisieren. Die spezifischen Möglichkeiten hängen von deinem Identitätsanbieter und den angeforderten Scopes ab. Siehe die Anleitung zum Abrufen gespeicherter Tokens für den API-Zugriff. + +## Soziale Identität des Benutzers verwalten \{#manage-user-s-social-identity} + +Nachdem ein Benutzer sein soziales Konto verknüpft hat, können Administratoren diese Verbindung in der Logto Console verwalten: + +1. Navigiere zu Logto Console > Benutzerverwaltung und öffne das Benutzerprofil. +2. Unter **Soziale Verbindungen** finde den Identitätsanbieter-Eintrag und klicke auf **Verwalten**. +3. Auf dieser Seite können Administratoren die soziale Verbindung des Benutzers verwalten, alle gewährten und synchronisierten Profilinformationen aus dem sozialen Konto einsehen und den Status des Zugangstokens überprüfen. + +:::note +Einige Identitätsanbieter geben im Zugangstoken-Response keine spezifischen Scope-Informationen zurück, sodass Logto die Liste der vom Benutzer gewährten Berechtigungen nicht direkt anzeigen kann. Solange der Benutzer jedoch den angeforderten Scopes während der Autorisierung zugestimmt hat, hat deine Anwendung beim Zugriff auf die OAuth-API die entsprechenden Berechtigungen. +::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index 0fd796e9c94..c06e065810e 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -2,9 +2,9 @@ slug: /integrations/oidc sidebar_label: OIDC (Sozial) sidebar_custom_props: - description: OpenID Connect 1.0 ist eine einfache Identitätsschicht über dem OAuth 2.0-Protokoll. + description: OpenID Connect 1.0 ist eine einfache Identitätsschicht auf dem OAuth 2.0-Protokoll. tutorial_name: OIDC -tutorial_config_name: Standard OIDC-App +tutorial_config_name: Standard OIDC app --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -13,17 +13,27 @@ import Integration from './_integration.mdx'; # Soziale Anmeldung mit OpenID Connect (OIDC) einrichten -Der offizielle Logto-Connector für das OpenID Connect (OIDC)-Protokoll. +Der offizielle Logto Connector für das OpenID Connect (OIDC) Protokoll. ## Erste Schritte \{#get-started} -Der OIDC-Connector ermöglicht Logtos Verbindung zu einem beliebigen sozialen Identitätsanbieter, der das OIDC-Protokoll unterstützt. +Der OIDC Connector ermöglicht die Verbindung von Logto zu einem beliebigen sozialen Identitätsanbieter, der das OIDC-Protokoll unterstützt. Verwende den OIDC Connector, um deiner Anwendung zu ermöglichen: + +- Soziale Anmeldebuttons hinzuzufügen +- Benutzerkonten mit sozialen Identitäten zu verknüpfen +- Benutzerprofilinformationen vom sozialen Anbieter zu synchronisieren +- Auf Drittanbieter-APIs zuzugreifen durch sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben (z. B. Bearbeiten von Google Docs, Verwalten von Kalenderereignissen in deiner App) + +Um diese Authentifizierungsfunktionen einzurichten, erstelle zuerst einen OIDC Connector in Logto: + +1. Gehe zu Logto-Konsole > Connector > Sozialer Connector. +2. Klicke auf **Sozialen Connector hinzufügen**, wähle **OIDC**, klicke auf **Weiter** und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen. :::note -Der OIDC-Connector ist eine spezielle Art von Connector in Logto, du kannst einige OIDC-basierte Connectors hinzufügen. +Der OIDC Connector ist eine besondere Art von Connector in Logto, du kannst mehrere auf dem OIDC-Protokoll basierende Connectoren hinzufügen. ::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index dcf205d2b36..58352219203 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,45 +1,45 @@ ## Erstelle deine OIDC-App \{#create-your-oidc-app} -Wenn du diese Seite öffnest, gehen wir davon aus, dass du bereits weißt, mit welchem sozialen Identitätsanbieter du dich verbinden möchtest. Das Erste, was du tun solltest, ist zu bestätigen, dass der Identitätsanbieter das OIDC-Protokoll unterstützt, da dies eine Voraussetzung für die Konfiguration eines gültigen Connectors ist. Folge dann den Anweisungen des Identitätsanbieters, um die relevante App für die OIDC-Autorisierung zu registrieren und zu erstellen. +Wenn du diese Seite öffnest, gehen wir davon aus, dass du bereits weißt, mit welchem sozialen Identitätsanbieter du dich verbinden möchtest. Das Erste, was du tun solltest, ist zu bestätigen, dass der Identitätsanbieter das OIDC-Protokoll unterstützt, da dies eine Voraussetzung für die Konfiguration eines gültigen Connectors ist. Folge dann den Anweisungen des Identitätsanbieters, um die entsprechende App für die OIDC-Autorisierung zu registrieren und zu erstellen. ## Konfiguriere deinen Connector \{#configure-your-connector} -Wir unterstützen aus Sicherheitsgründen NUR den "Authorization Code"-Grant-Typ, und er passt perfekt zu Logtos Szenario. +Wir unterstützen AUSSCHLIESSLICH den "Authorization Code" Grant-Typ aus Sicherheitsgründen, und dieser passt perfekt zum Szenario von Logto. -`clientId` und `clientSecret` findest du auf der Detailseite deiner OIDC-Apps. +`clientId` und `clientSecret` findest du auf der Detailseite deiner OIDC-App. -_clientId_: Die Client-ID ist ein eindeutiger Identifikator, der die Client-Anwendung während der Registrierung beim Autorisierungsserver identifiziert. Diese ID wird vom Autorisierungsserver verwendet, um die Identität der Client-Anwendung zu überprüfen und um alle autorisierten Zugangstokens mit dieser spezifischen Client-Anwendung zu verknüpfen. +_clientId_: Die Client-ID ist ein eindeutiger Bezeichner, der die Client-Anwendung während der Registrierung beim Autorisierungsserver identifiziert. Diese ID wird vom Autorisierungsserver verwendet, um die Identität der Client-Anwendung zu überprüfen und alle autorisierten Zugangstokens mit dieser spezifischen Client-Anwendung zu verknüpfen. -_clientSecret_: Das Client-Secret ist ein vertraulicher Schlüssel, der der Client-Anwendung vom Autorisierungsserver während der Registrierung ausgestellt wird. Die Client-Anwendung verwendet diesen geheimen Schlüssel, um sich beim Autorisierungsserver zu authentifizieren, wenn sie Zugangstokens anfordert. Das Client-Secret wird als vertrauliche Information betrachtet und sollte jederzeit sicher aufbewahrt werden. +_clientSecret_: Das Client-Secret ist ein vertraulicher Schlüssel, der der Client-Anwendung vom Autorisierungsserver während der Registrierung zugewiesen wird. Die Client-Anwendung verwendet diesen geheimen Schlüssel, um sich beim Autorisierungsserver zu authentifizieren, wenn Zugangstokens angefordert werden. Das Client-Secret gilt als vertrauliche Information und sollte stets sicher aufbewahrt werden. -_tokenEndpointAuthMethod_: Die Authentifizierungsmethode des Token-Endpunkts wird von der Client-Anwendung verwendet, um sich beim Autorisierungsserver zu authentifizieren, wenn Zugangstokens angefordert werden. Um unterstützte Methoden zu entdecken, konsultiere das Feld `token_endpoint_auth_methods_supported`, das am OpenID Connect Discovery-Endpunkt des OAuth 2.0-Dienstanbieters verfügbar ist, oder beziehe dich auf die relevante Dokumentation des OAuth 2.0-Dienstanbieters. +_tokenEndpointAuthMethod_: Die Authentifizierungsmethode für den Token-Endpunkt wird von der Client-Anwendung verwendet, um sich beim Autorisierungsserver zu authentifizieren, wenn Zugangstokens angefordert werden. Um unterstützte Methoden zu entdecken, konsultiere das Feld `token_endpoint_auth_methods_supported`, das am OpenID Connect Discovery-Endpunkt des OAuth 2.0-Dienstanbieters verfügbar ist, oder schaue in die entsprechende Dokumentation des OAuth 2.0-Dienstanbieters. -_clientSecretJwtSigningAlgorithm (Optional)_: Nur erforderlich, wenn `tokenEndpointAuthMethod` `client_secret_jwt` ist. Der Client-Secret-JWT-Signaturalgorithmus wird von der Client-Anwendung verwendet, um das JWT zu signieren, das während der Token-Anfrage an den Autorisierungsserver gesendet wird. +_clientSecretJwtSigningAlgorithm (Optional)_: Nur erforderlich, wenn `tokenEndpointAuthMethod` auf `client_secret_jwt` gesetzt ist. Der Client-Secret-JWT-Signaturalgorithmus wird von der Client-Anwendung verwendet, um das JWT zu signieren, das während der Token-Anfrage an den Autorisierungsserver gesendet wird. -_scope_: Der Scope-Parameter wird verwendet, um die Menge der Ressourcen und Berechtigungen anzugeben, auf die die Client-Anwendung zugreifen möchte. Der Scope-Parameter wird typischerweise als durch Leerzeichen getrennte Liste von Werten definiert, die spezifische Berechtigungen darstellen. Zum Beispiel könnte ein Scope-Wert von "read write" anzeigen, dass die Client-Anwendung Lese- und Schreibzugriff auf die Daten eines Benutzers anfordert. +_scope_: Der Scope-Parameter wird verwendet, um die Menge an Ressourcen und Berechtigungen anzugeben, auf die die Client-Anwendung zugreifen möchte. Der Scope-Parameter wird typischerweise als durch Leerzeichen getrennte Liste von Werten definiert, die bestimmte Berechtigungen darstellen. Zum Beispiel könnte ein Scope-Wert von "read write" anzeigen, dass die Client-Anwendung Lese- und Schreibzugriff auf die Daten eines Benutzers anfordert. -Du solltest `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` und `issuer` als Konfigurationsinformationen des OpenID Providers finden. Diese sollten in der Dokumentation des sozialen Anbieters verfügbar sein. +Du solltest `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` und `issuer` als Konfigurationsinformationen des OpenID-Providers finden. Sie sollten in der Dokumentation des sozialen Anbieters verfügbar sein. -_authenticationEndpoint_: Dieser Endpunkt wird verwendet, um den Authentifizierungsprozess zu initiieren. Der Authentifizierungsprozess beinhaltet typischerweise, dass sich der Benutzer anmeldet und der Client-Anwendung die Berechtigung erteilt, auf seine Ressourcen zuzugreifen. +_authenticationEndpoint_: Dieser Endpunkt wird verwendet, um den Authentifizierungsprozess zu starten. Der Authentifizierungsprozess beinhaltet typischerweise, dass sich der Benutzer anmeldet und der Client-Anwendung die Berechtigung erteilt, auf seine Ressourcen zuzugreifen. _tokenEndpoint_: Dieser Endpunkt wird von der Client-Anwendung verwendet, um ein ID-Token zu erhalten, das zum Zugriff auf die angeforderten Ressourcen verwendet werden kann. Die Client-Anwendung sendet typischerweise eine Anfrage an den Token-Endpunkt mit einem Grant-Typ und einem Autorisierungscode, um ein ID-Token zu erhalten. -_jwksUri_: Dies ist der URL-Endpunkt, an dem das JSON Web Key Set (JWKS) des sozialen Identitätsanbieters (kurz IdP) abgerufen werden kann. Das JWKS ist eine Sammlung kryptografischer Schlüssel, die der IdP verwendet, um JSON Web Tokens (JWTs) zu signieren und zu verifizieren, die während des Authentifizierungsprozesses ausgestellt werden. Die `jwksUri` wird von der vertrauenden Partei (RP) verwendet, um die öffentlichen Schlüssel zu erhalten, die vom IdP zum Signieren der JWTs verwendet werden, sodass die RP die Authentizität und Integrität der vom IdP empfangenen JWTs überprüfen kann. +_jwksUri_: Dies ist die URL des Endpunkts, an dem das JSON Web Key Set (JWKS) des sozialen Identitätsanbieters (kurz IdP) abgerufen werden kann. Das JWKS ist eine Sammlung kryptografischer Schlüssel, die der IdP verwendet, um JSON Web Tokens (JWTs) zu signieren und zu verifizieren, die während des Authentifizierungsprozesses ausgegeben werden. Die `jwksUri` wird von der vertrauenden Partei (RP) verwendet, um die öffentlichen Schlüssel zu erhalten, die vom IdP zum Signieren der JWTs verwendet werden, sodass die RP die Authentizität und Integrität der vom IdP empfangenen JWTs überprüfen kann. -_issuer_: Dies ist der eindeutige Identifikator des IdP, der von der RP verwendet wird, um die vom IdP empfangenen JWTs zu überprüfen. Er ist in den JWTs als `iss` [Anspruch](https://www.rfc-editor.org/rfc/rfc7519#section-4) enthalten (ID-Token ist immer ein JWT). Der Ausstellerwert sollte mit der URL des Autorisierungsservers des IdP übereinstimmen und eine URI sein, der die RP vertraut. Wenn die RP ein JWT erhält, überprüft sie den `iss`-Anspruch, um sicherzustellen, dass es von einem vertrauenswürdigen IdP ausgestellt wurde und dass das JWT für die Verwendung mit der RP bestimmt ist. +_issuer_: Dies ist der eindeutige Bezeichner des IdP, der von der RP verwendet wird, um die vom IdP empfangenen JWTs zu überprüfen. Er ist in den JWTs als `iss` [Anspruch (Claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4) enthalten (ID-Token ist immer ein JWT). Der Wert des Issuers sollte mit der URL des Autorisierungsservers des IdP übereinstimmen und eine URI sein, der die RP vertraut. Wenn die RP ein JWT erhält, prüft sie den `iss`-Anspruch, um sicherzustellen, dass es von einem vertrauenswürdigen IdP ausgestellt wurde und dass das JWT für die Verwendung mit der RP bestimmt ist. -Zusammen bieten `jwksUri` und `issuer` einen sicheren Mechanismus für die RP, um die Identität des Endbenutzers während des Authentifizierungsprozesses zu überprüfen. Durch die Verwendung der von der `jwksUri` erhaltenen öffentlichen Schlüssel kann die RP die Authentizität und Integrität der vom IdP ausgestellten JWTs überprüfen. Der Ausstellerwert stellt sicher, dass die RP nur JWTs akzeptiert, die von einem vertrauenswürdigen IdP ausgestellt wurden und dass die JWTs für die Verwendung mit der RP bestimmt sind. +Zusammen bieten `jwksUri` und `issuer` einen sicheren Mechanismus für die RP, um die Identität des Endbenutzers während des Authentifizierungsprozesses zu überprüfen. Durch die Verwendung der von der `jwksUri` erhaltenen öffentlichen Schlüssel kann die RP die Authentizität und Integrität der vom IdP ausgestellten JWTs überprüfen. Der Wert des Issuers stellt sicher, dass die RP nur JWTs akzeptiert, die von einem vertrauenswürdigen IdP ausgestellt wurden und dass die JWTs für die Verwendung mit der RP bestimmt sind. -Da eine Authentifizierungsanfrage immer erforderlich ist, wird ein `authRequestOptionalConfig` bereitgestellt, um alle optionalen Konfigurationen zu umschließen. Details findest du unter [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Du wirst vielleicht auch feststellen, dass `nonce` in dieser Konfiguration fehlt. Da `nonce` für jede Anfrage identisch sein sollte, haben wir die Generierung von `nonce` in die Code-Implementierung aufgenommen. Also mach dir keine Sorgen darüber! Die zuvor erwähnten `jwksUri` und `issuer` sind ebenfalls in `idTokenVerificationConfig` enthalten. +Da immer eine Authentifizierungsanfrage erforderlich ist, wird ein `authRequestOptionalConfig` bereitgestellt, um alle optionalen Konfigurationen zu bündeln. Details findest du unter [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Du wirst vielleicht feststellen, dass `nonce` in dieser Konfiguration fehlt. Da `nonce` für jede Anfrage identisch sein sollte, haben wir die Generierung von `nonce` in die Code-Implementierung verlagert. Also keine Sorge! Die zuvor erwähnten `jwksUri` und `issuer` sind ebenfalls in `idTokenVerificationConfig` enthalten. -Du fragst dich vielleicht, warum ein standardmäßiges OIDC-Protokoll sowohl die impliziten als auch die hybriden Flows unterstützt, während der Logto-Connector nur den Autorisierungs-Flow unterstützt. Es wurde festgestellt, dass die impliziten und hybriden Flows weniger sicher sind als der Autorisierungs-Flow. Aufgrund von Logtos Fokus auf Sicherheit unterstützt es nur den Autorisierungs-Flow für das höchste Sicherheitsniveau für seine Benutzer, trotz seiner etwas weniger bequemen Natur. +Du fragst dich vielleicht, warum ein standardisiertes OIDC-Protokoll sowohl den Implicit- als auch den Hybrid-Flow unterstützt, der Logto-Connector jedoch nur den Authorization-Flow. Es wurde festgestellt, dass die Implicit- und Hybrid-Flows weniger sicher sind als der Authorization-Flow. Aufgrund des Fokus von Logto auf Sicherheit wird ausschließlich der Authorization-Flow unterstützt, um das höchste Sicherheitsniveau für die Nutzer zu gewährleisten, auch wenn dies etwas weniger bequem ist. -`responseType` und `grantType` können NUR feste Werte mit dem "Authorization Code"-Flow sein, daher machen wir sie optional und Standardwerte werden automatisch ausgefüllt. +`responseType` und `grantType` können NUR FESTE Werte im "Authorization Code"-Flow haben, daher machen wir sie optional und Standardwerte werden automatisch ausgefüllt. :::note -Für alle Flow-Typen haben wir einen OPTIONALEN `customConfig`-Schlüssel bereitgestellt, um deine benutzerdefinierten Parameter einzufügen. -Jeder soziale Identitätsanbieter könnte seine eigene Variante des OIDC-Standardprotokolls haben. Wenn dein gewünschter sozialer Identitätsanbieter strikt am OIDC-Standardprotokoll festhält, musst du dich nicht um `customConfig` kümmern. +Für alle Flow-Typen haben wir einen OPTIONALEN `customConfig`-Schlüssel bereitgestellt, um deine individuellen Parameter einzutragen. +Jeder soziale Identitätsanbieter kann seine eigene Variante des OIDC-Standardprotokolls haben. Wenn dein gewünschter sozialer Identitätsanbieter strikt dem OIDC-Standardprotokoll folgt, musst du dich nicht um `customConfig` kümmern. ::: @@ -56,30 +56,96 @@ Jeder soziale Identitätsanbieter könnte seine eigene Variante des OIDC-Standar | authRequestOptionalConfig | AuthRequestOptionalConfig | Nein | | customConfig | Record\ | Nein | -| AuthRequestOptionalConfig Eigenschaften | Typ | Erforderlich | -| --------------------------------------- | ------ | ------------ | -| responseType | string | Nein | -| tokenEndpoint | string | Nein | -| responseMode | string | Nein | -| display | string | Nein | -| prompt | string | Nein | -| maxAge | string | Nein | -| uiLocales | string | Nein | -| idTokenHint | string | Nein | -| loginHint | string | Nein | -| acrValues | string | Nein | - -| IdTokenVerificationConfig Eigenschaften | Typ | Erforderlich | -| --------------------------------------- | ---------------------------------- | ------------ | -| jwksUri | string | Ja | -| issuer | string \| string[] | Nein | -| audience | string \| string[] | Nein | -| algorithms | string[] | Nein | -| clockTolerance | string \| number | Nein | -| crit | Record\ | Nein | -| currentDate | Date | Nein | -| maxTokenAge | string \| number | Nein | -| subject | string | Nein | -| typ | string | Nein | - -Siehe [hier](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md), um mehr Details über `IdTokenVerificationConfig` zu finden. +| Eigenschaften von AuthRequestOptionalConfig | Typ | Erforderlich | +| ------------------------------------------- | ------ | ------------ | +| responseType | string | Nein | +| tokenEndpoint | string | Nein | +| responseMode | string | Nein | +| display | string | Nein | +| prompt | string | Nein | +| maxAge | string | Nein | +| uiLocales | string | Nein | +| idTokenHint | string | Nein | +| loginHint | string | Nein | +| acrValues | string | Nein | + +| Eigenschaften von IdTokenVerificationConfig | Typ | Erforderlich | +| ------------------------------------------- | ---------------------------------- | ------------ | +| jwksUri | string | Ja | +| issuer | string \| string[] | Nein | +| audience | string \| string[] | Nein | +| algorithms | string[] | Nein | +| clockTolerance | string \| number | Nein | +| crit | Record\ | Nein | +| currentDate | Date | Nein | +| maxTokenAge | string \| number | Nein | +| subject | string | Nein | +| typ | string | Nein | + +Weitere Details zu `IdTokenVerificationConfig` findest du [hier](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md). + +## Allgemeine Einstellungen \{#general-settings} + +Hier sind einige allgemeine Einstellungen, die die Verbindung zu deinem Identitätsanbieter nicht blockieren, aber das Authentifizierungserlebnis für Endbenutzer beeinflussen können. + +### Name und Logo des Social-Buttons \{#social-button-name-and-logo} + +Wenn du einen Social-Button auf deiner Anmeldeseite anzeigen möchtest, kannst du den **Namen** und das **Logo** (Dark Mode und Light Mode) des sozialen Identitätsanbieters festlegen. Dies hilft den Nutzern, die Option für die soziale Anmeldung zu erkennen. + +### Name des Identitätsanbieters \{#identity-provider-name} + +Jeder Social-Connector hat einen eindeutigen Identitätsanbieter (IdP)-Namen, um Benutzeridentitäten zu unterscheiden. Während gängige Connectoren einen festen IdP-Namen verwenden, benötigen benutzerdefinierte Connectoren einen eindeutigen Wert. Erfahre mehr über [IdP-Namen](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) für weitere Details. + +### Profilinformationen synchronisieren \{#sync-profile-information} + +Im OIDC-Connector kannst du die Richtlinie für das Synchronisieren von Profilinformationen wie Benutzernamen und Avataren festlegen. Wähle aus: + +- **Nur beim ersten Anmelden synchronisieren**: Profilinformationen werden einmalig beim ersten Anmelden des Benutzers abgerufen. +- **Immer beim Anmelden synchronisieren**: Profilinformationen werden jedes Mal aktualisiert, wenn sich der Benutzer anmeldet. + +### Tokens speichern, um auf Drittanbieter-APIs zuzugreifen (Optional) \{#store-tokens-to-access-third-party-apis-optional} + +Wenn du auf die APIs des Identitätsanbieters zugreifen und Aktionen mit Benutzerautorisierung durchführen möchtest (entweder über Social Sign-In oder Account Linking), muss Logto bestimmte API-Berechtigungen erhalten und Tokens speichern. + +1. Füge die erforderlichen Berechtigungen im **scope**-Feld gemäß den obigen Anweisungen hinzu. +2. Aktiviere **Tokens für dauerhaften API-Zugriff speichern** im Logto OIDC-Connector. Logto speichert Zugangstokens sicher im Secret Vault. +3. Für **standardisierte** OAuth/OIDC-Identitätsanbieter muss der `offline_access`-Scope enthalten sein, um ein Auffrischungstoken zu erhalten und wiederholte Benutzerzustimmungsaufforderungen zu vermeiden. + +:::warning +Halte dein Client-Secret sicher und veröffentliche es niemals im Client-seitigen Code. Wenn es kompromittiert wird, generiere sofort ein neues in den App-Einstellungen deines Identitätsanbieters. +::: + +## OIDC-Connector nutzen \{#utilize-the-oidc-connector} + +Sobald du einen OIDC-Connector erstellt und mit deinem Identitätsanbieter verbunden hast, kannst du ihn in deine Endbenutzer-Flows integrieren. Wähle die Optionen, die zu deinen Anforderungen passen: + +### Social Sign-In-Button aktivieren \{#enable-social-sign-in-button} + +1. Gehe in der Logto-Konsole zu Anmeldeerlebnis > Registrierung und Anmeldung. +2. Füge den OIDC-Connector im Abschnitt **Social Sign-In** hinzu, damit Benutzer sich mit deinem Identitätsanbieter authentifizieren können. + +Erfahre mehr über die [Social Sign-In-Erfahrung](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Ein soziales Konto verknüpfen oder trennen \{#link-or-unlink-a-social-account} + +Nutze die Account API, um ein benutzerdefiniertes Account Center in deiner App zu erstellen, das angemeldeten Benutzern das Verknüpfen oder Trennen ihrer sozialen Konten ermöglicht. [Folge dem Account API-Tutorial](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Es ist erlaubt, den OIDC-Connector nur für Account Linking und API-Zugriff zu aktivieren, ohne ihn für Social Sign-In zu aktivieren. +::: + +### Auf APIs des Identitätsanbieters zugreifen und Aktionen durchführen \{#access-identity-provider-apis-and-perform-actions} + +Deine Anwendung kann gespeicherte Zugangstokens aus dem Secret Vault abrufen, um die APIs deines Identitätsanbieters aufzurufen und Backend-Aufgaben zu automatisieren. Die spezifischen Möglichkeiten hängen von deinem Identitätsanbieter und den angeforderten Berechtigungen ab. Siehe die Anleitung zum Abrufen gespeicherter Tokens für den API-Zugriff. + +## Soziale Identität des Benutzers verwalten \{#manage-user-s-social-identity} + +Nachdem ein Benutzer sein soziales Konto verknüpft hat, können Administratoren diese Verbindung in der Logto-Konsole verwalten: + +1. Navigiere zu Logto-Konsole > Benutzerverwaltung und öffne das Profil des Benutzers. +2. Unter **Soziale Verbindungen** finde den Eintrag des Identitätsanbieters und klicke auf **Verwalten**. +3. Auf dieser Seite können Administratoren die soziale Verbindung des Benutzers verwalten, alle gewährten und synchronisierten Profilinformationen aus dem sozialen Konto einsehen und den Status des Zugangstokens überprüfen. + +:::note +Einige Identitätsanbieter geben im Access Token Response keine spezifischen Scope-Informationen zurück, sodass Logto die Liste der vom Benutzer gewährten Berechtigungen nicht direkt anzeigen kann. Solange der Benutzer jedoch den angeforderten Berechtigungen während der Autorisierung zugestimmt hat, hat deine Anwendung beim Zugriff auf die OIDC-API die entsprechenden Berechtigungen. +::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index 1e91a0e3ece..161d5bcef21 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: Einheitliches und sicheres Management des Benutzerzugangs innerhalb des Google-Ökosystems. + description: Einheitliche und sichere Verwaltung des Benutzerzugriffs innerhalb des Google-Ökosystems. (Unified and secure management of user access within the Google ecosystem.) logoFilename: 'google.svg' tutorial_name: Google Workspace enterprise SSO tutorial_config_name: Google Cloud Platform @@ -16,6 +16,7 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; # Single Sign-On mit Google Workspace einrichten @@ -31,11 +32,11 @@ Mit minimalem Konfigurationsaufwand ermöglicht dieser Connector die Integration -## Schritt 3: Ein neues OAuth-Anmeldeinformation erstellen \{#step-3-create-a-new-oauth-credential} +## Schritt 3: Neue OAuth-Anmeldedaten erstellen \{#step-3-create-a-new-oauth-credential} -## Schritt 4: Logto-Connector mit den Client-Anmeldeinformationen einrichten \{#step-4-set-up-logto-connector-with-the-client-credentials} +## Schritt 4: Logto-Connector mit den Client-Anmeldedaten einrichten \{#step-4-set-up-logto-connector-with-the-client-credentials} @@ -43,6 +44,10 @@ Mit minimalem Konfigurationsaufwand ermöglicht dieser Connector die Integration -## Schritt 6: E-Mail-Domains festlegen und den SSO-Connector aktivieren \{#step-6-set-email-domains-and-enable-the-sso-connector} +## Schritt 6: Tokens speichern, um auf Google APIs zuzugreifen (Optional) \{#step-6-store-tokens-to-access-google-apis-optional} + +## Schritt 7: E-Mail-Domains festlegen und den SSO-Connector aktivieren \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index eb516dcde60..58d2860f9cb 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,20 +4,21 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -### Schritt 1: Ein neues Projekt auf der Google Cloud Platform erstellen \{#step-1-create-a-new-project-on-google-cloud-platform} +### Schritt 1: Erstelle ein neues Projekt auf der Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} -### Schritt 2: Den Zustimmungsbildschirm für deine Anwendung konfigurieren \{#step-2-config-the-consent-screen-for-your-application} +### Schritt 2: Konfiguriere den Zustimmungsbildschirm (Consent Screen) für deine Anwendung \{#step-2-config-the-consent-screen-for-your-application} -### Schritt 3: Ein neues OAuth-Anmeldedaten erstellen \{#step-3-create-a-new-oauth-credential} +### Schritt 3: Erstelle eine neue OAuth-Anmeldeinformation \{#step-3-create-a-new-oauth-credential} -### Schritt 4: Logto-Connector mit den Client-Anmeldedaten einrichten \{#step-4-set-up-logto-connector-with-the-client-credentials} +### Schritt 4: Richte den Logto Connector mit den Client-Zugangsdaten ein \{#step-4-set-up-logto-connector-with-the-client-credentials} @@ -25,6 +26,10 @@ import Step6 from './_step-6.mdx'; -### Schritt 6: E-Mail-Domänen festlegen und den SSO-Connector aktivieren \{#step-6-set-email-domains-and-enable-the-sso-connector} +### Schritt 6: Tokens speichern, um auf Google APIs zuzugreifen (Optional) \{#step-6-store-tokens-to-access-google-apis-optional} + +### Schritt 7: E-Mail-Domains festlegen und den SSO Connector aktivieren \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index e70ed413664..bf3f9c0eec0 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -Verwende das Feld `Scope`, um zusätzliche Berechtigungen zu deiner OAuth-Anfrage hinzuzufügen. Dadurch kannst du mehr Informationen vom Google OAuth-Server anfordern. Bitte sieh dir die [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) Dokumentation für weitere Informationen an. +Berechtigungen (Scopes) definieren die Berechtigungen, die deine App von den Benutzern anfordert, und steuern, auf welche Daten deine App in deren Google Workspace-Konten zugreifen kann. Das Anfordern von Google-Berechtigungen erfordert eine Konfiguration auf beiden Seiten: -Unabhängig von den benutzerdefinierten Berechtigungseinstellungen wird Logto immer die Berechtigungen `openid`, `profile` und `email` an den Identitätsanbieter (IdP) senden. Dies stellt sicher, dass Logto die Identitätsinformationen und die E-Mail-Adresse des Benutzers ordnungsgemäß abrufen kann. +**In der Google Cloud Console:** + +1. Navigiere zu **APIs & Dienste > OAuth-Zustimmungsbildschirm > Berechtigungen (Scopes)**. +2. Klicke auf **Berechtigungen hinzufügen oder entfernen** und wähle nur die Berechtigungen aus, die deine App benötigt: + - Authentifizierung (Authentication) (Erforderlich): + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - API-Zugriff (Optional): Füge alle zusätzlichen Berechtigungen hinzu, die deine App benötigt (z. B. Drive, Kalender, YouTube). Durchsuche die [Google API-Bibliothek](https://console.cloud.google.com/apis/library), um verfügbare Dienste zu finden. Wenn deine App Zugriff auf Google APIs über die grundlegenden Berechtigungen hinaus benötigt, aktiviere zuerst die spezifischen APIs, die deine App verwenden wird (z. B. Google Drive API, Gmail API, Kalender API) in der Google API-Bibliothek. +3. Klicke auf **Aktualisieren**, um die Auswahl zu bestätigen. +4. Klicke auf **Speichern und fortfahren**, um die Änderungen zu übernehmen. + +**Im Logto Google Workspace Connector:** + +1. Logto fügt automatisch die Berechtigungen `openid`, `profile` und `email` hinzu, um grundlegende Benutzeridentitätsinformationen abzurufen. Du kannst das Feld `Scopes` leer lassen, wenn du nur grundlegende Benutzerinformationen benötigst. +2. Füge zusätzliche Berechtigungen (durch Leerzeichen getrennt) im Feld `Scopes` hinzu, um mehr Daten von Google anzufordern. Verwende vollständige Scope-URLs, zum Beispiel: `https://www.googleapis.com/auth/calendar.readonly` + +:::tip +Wenn deine App diese Berechtigungen anfordert, um auf die Google API zuzugreifen und Aktionen auszuführen, stelle sicher, dass du **Tokens für dauerhaften API-Zugriff speichern** im Logto Google Connector aktivierst. Siehe den nächsten Abschnitt für Details. +::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index a166edfd08e..bf17485b7be 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -Gib die `E-Mail-Domains` deiner Organisation auf der Registerkarte `SSO-Erfahrung` des Logto-Connectors an. Dadurch wird der SSO-Connector als Authentifizierungsmethode für diese Benutzer aktiviert. +Wenn du auf [Google APIs](https://console.cloud.google.com/apis/library) zugreifen und Aktionen mit Benutzer-Autorisierung durchführen möchtest, muss Logto bestimmte API-Berechtigungen (Scopes) erhalten und Tokens speichern. -Benutzer mit E-Mail-Adressen in den angegebenen Domains werden weitergeleitet, um deinen SSO-Connector als einzige Authentifizierungsmethode zu verwenden. +1. Füge die erforderlichen Berechtigungen (Scopes) in deiner Google Cloud Console OAuth-Zustimmungsbildschirm-Konfiguration und im Logto Google Connector hinzu. +2. Aktiviere **Tokens für dauerhaften API-Zugriff speichern** im Logto Google Connector. Logto speichert Google Zugangstokens (Access tokens) und Auffrischungstokens (Refresh tokens) sicher im Secret Vault. +3. Um sicherzustellen, dass Auffrischungstokens (Refresh tokens) zurückgegeben werden, konfiguriere deinen Logto Google Connector so, dass **Offline-Zugriff** aktiviert ist. -Für weitere Informationen über den Google Workspace SSO-Connector, siehe bitte [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). +:::warning +Du musst `offline_access` nicht im Logto `Scope`-Feld hinzufügen — dies kann zu einem Fehler führen. Google verwendet automatisch `access_type=offline`, wenn Offline-Zugriff aktiviert ist. +::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..57d5502b34e --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +Gib die `E-Mail-Domains` deiner Organisation im Tab `SSO-Erfahrung` des Logto-Connectors an. Dadurch wird der SSO-Connector als Authentifizierungsmethode für diese Benutzer aktiviert. + +Benutzer mit E-Mail-Adressen in den angegebenen Domains werden weitergeleitet, um deinen SSO-Connector als einzige Authentifizierungsmethode zu verwenden. + +Weitere Informationen zum Google Workspace SSO-Connector findest du unter [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 7ecf5c40cee..136f2fcbdee 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -2,10 +2,10 @@ slug: /integrations/oidc-sso sidebar_label: OIDC (Enterprise) sidebar_custom_props: - description: Modernes Protokoll, das auf OAuth 2.0 für die Identitätsüberprüfung in Web- und mobilen Apps basiert. + description: Modernes Protokoll, das auf OAuth 2.0 basiert, zur Identitätsüberprüfung in Web- und mobilen Apps. logoFilename: 'oidc.svg' tutorial_name: OIDC enterprise SSO -tutorial_config_name: OIDC-Anwendung auf deinem IdP +tutorial_config_name: OIDC application on your IdP --- import GuideTip from '../../fragments/_sso_guide_tip.mdx'; @@ -13,6 +13,8 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; # Single Sign-On mit OpenID Connect (OIDC) einrichten @@ -20,14 +22,22 @@ Mit minimalem Konfigurationsaufwand ermöglicht dieser Connector die Integration -## Schritt 1: Erstelle eine OIDC-Anwendung auf deinem IdP \{#step-1-create-an-oidc-application-on-your-idp} +## Schritt 1: OIDC-Anwendung auf deinem IdP erstellen \{#step-1-create-an-oidc-application-on-your-idp} -## Schritt 2: OIDC SSO auf Logto konfigurieren \{#step-2-configure-oidc-sso-on-logto} +## Schritt 2: OIDC SSO in Logto konfigurieren \{#step-2-configure-oidc-sso-on-logto} -## Schritt 3: E-Mail-Domänen festlegen und den SSO-Connector aktivieren \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Schritt 3: Berechtigungen (Scopes) konfigurieren (Optional) \{#step-3-configure-scopes-optional} + +## Schritt 4: Tokens speichern, um auf Drittanbieter-APIs zuzugreifen (Optional) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Schritt 5: E-Mail-Domains festlegen und den SSO-Connector aktivieren \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index eafb7b55529..b0f86440c4d 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,15 +1,25 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; -### Schritt 1: Erstelle eine OIDC-Anwendung auf deinem IdP \{#step-1-create-an-oidc-application-on-your-idp} +### Schritt 1: Erstelle eine OIDC-Anwendung bei deinem IdP \{#step-1-create-an-oidc-application-on-your-idp} -### Schritt 2: Konfiguriere OIDC SSO auf Logto \{#step-2-configure-oidc-sso-on-logto} +### Schritt 2: Konfiguriere OIDC SSO in Logto \{#step-2-configure-oidc-sso-on-logto} -### Schritt 3: Setze E-Mail-Domänen und aktiviere den SSO-Connector \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Schritt 3: Berechtigungen konfigurieren (optional) \{#step-3-configure-scopes-optional} + +## Schritt 4: Tokens speichern, um auf Drittanbieter-APIs zuzugreifen (optional) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Schritt 5: E-Mail-Domains festlegen und den SSO-Connector aktivieren \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index 66834ef8d16..47b6f01a17a 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ Nachdem du erfolgreich eine OIDC-Anwendung auf der IdP-Seite erstellt hast, musst du die IdP-Konfigurationen an Logto zurückgeben. Navigiere zum Tab `Connection` und fülle die folgenden Konfigurationen aus: -- **Client ID**: Ein eindeutiger Bezeichner, der deiner OIDC-Anwendung vom IdP zugewiesen wird. Dieser Bezeichner wird von Logto verwendet, um die Anwendung während des OIDC-Flows zu identifizieren und zu authentifizieren. +- **Client ID**: Ein eindeutiger Bezeichner, der deiner OIDC-Anwendung vom IdP zugewiesen wurde. Dieser Bezeichner wird von Logto verwendet, um die Anwendung während des OIDC-Flows zu identifizieren und zu authentifizieren. - **Client Secret**: Ein vertrauliches Geheimnis, das zwischen Logto und dem IdP geteilt wird. Dieses Geheimnis wird verwendet, um die OIDC-Anwendung zu authentifizieren und die Kommunikation zwischen Logto und dem IdP abzusichern. -- **Aussteller (Issuer)**: Die Aussteller-URL, ein eindeutiger Bezeichner für den IdP, der den Ort angibt, an dem der OIDC-Identitätsanbieter gefunden werden kann. Sie ist ein wesentlicher Bestandteil der OIDC-Konfiguration, da sie Logto hilft, die erforderlichen Endpunkte zu entdecken. - Um den Konfigurationsprozess zu erleichtern, wird Logto automatisch die erforderlichen OIDC-Endpunkte und Konfigurationen abrufen. Dies geschieht, indem der von dir bereitgestellte Aussteller genutzt wird und ein Aufruf zu den OIDC-Entdeckungspunkten des IdP gemacht wird. Es ist zwingend erforderlich, sicherzustellen, dass der Aussteller-Endpunkt gültig und korrekt konfiguriert ist, damit Logto die erforderlichen Informationen korrekt abrufen kann. - Nach einem erfolgreichen Abruf solltest du die analysierten IdP-Konfigurationen im Abschnitt der Aussteller sehen können. -- **Berechtigung (Scope)**: Eine durch Leerzeichen getrennte Liste von Zeichenfolgen, die die gewünschten Berechtigungen oder Zugriffsebenen definieren, die von Logto während des OIDC-Authentifizierungsprozesses angefordert werden. Der Scope-Parameter ermöglicht es dir, anzugeben, welche Informationen und Zugriffe Logto vom IdP anfordert. - Der Scope-Parameter ist optional. Unabhängig von den benutzerdefinierten Scope-Einstellungen wird Logto immer die Berechtigungen `openid`, `profile` und `email` an den IdP senden. - Dies soll sicherstellen, dass Logto die Identitätsinformationen und die E-Mail-Adresse des Benutzers ordnungsgemäß vom IdP abrufen kann. Du kannst zusätzliche Berechtigungen zum Scope-Parameter hinzufügen, um mehr Informationen vom IdP anzufordern. +- **Aussteller (Issuer)**: Die Aussteller-URL, ein eindeutiger Bezeichner für den IdP, der den Ort angibt, an dem der OIDC-Identitätsanbieter gefunden werden kann. Sie ist ein entscheidender Bestandteil der OIDC-Konfiguration, da sie Logto hilft, die notwendigen Endpunkte zu entdecken. + Um den Konfigurationsprozess zu erleichtern, ruft Logto automatisch die erforderlichen OIDC-Endpunkte und Konfigurationen ab. Dies geschieht, indem der von dir angegebene Aussteller verwendet und ein Aufruf an die OIDC-Discovery-Endpunkte des IdP gemacht wird. Es ist zwingend erforderlich, sicherzustellen, dass der Aussteller-Endpunkt gültig und korrekt konfiguriert ist, damit Logto die benötigten Informationen korrekt abrufen kann. + Nach einem erfolgreichen Abruf solltest du die analysierten IdP-Konfigurationen im Bereich „Aussteller“ sehen können. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index 85cb98265ba..610755038c4 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -Gib die `E-Mail-Domains` deiner Organisation auf der `SSO-Erfahrung`-Registerkarte des Logto-Connectors an. Dadurch wird der SSO-Connector als Authentifizierungsmethode für diese Benutzer aktiviert. +Berechtigungen (Scopes) definieren die Berechtigungen, die deine App von den Benutzern anfordert, und steuern, auf welche Daten deine App in deren Unternehmenskonten zugreifen kann. -Benutzer mit E-Mail-Adressen in den angegebenen Domains werden weitergeleitet, um deinen SSO-Connector als einzige Authentifizierungsmethode zu verwenden. +Das Einrichten von Berechtigungen erfordert eine Konfiguration auf beiden Seiten: + +1. **Dein Identitätsanbieter (IdP)**: Konfiguriere, welche Berechtigungen für die Autorisierung in deiner IdP-Konsole erlaubt sind + - Einige IdPs aktivieren standardmäßig alle öffentlichen Berechtigungen (keine Aktion erforderlich) + - Andere erfordern, dass du Berechtigungen explizit gewährst +2. **Logto Enterprise Connector**: Gib an, welche Berechtigungen während der Authentifizierung im Logto OIDC Enterprise Connector unter Einstellungen > Feld `Scopes` angefordert werden sollen. + - Logto fügt immer die Berechtigungen `openid`, `profile` und `email` hinzu, um grundlegende Benutzeridentitätsinformationen abzurufen, unabhängig von deinen benutzerdefinierten Berechtigungseinstellungen. + - Du kannst zusätzliche Berechtigungen (durch Leerzeichen getrennt) hinzufügen, um weitere Informationen vom IdP anzufordern. + +:::tip +Wenn deine App APIs mit diesen Berechtigungen (Scopes) aufrufen muss, stelle sicher, dass du **Tokens für dauerhaften API-Zugriff speichern** im Logto Enterprise Connector aktivierst. Siehe den nächsten Abschnitt für Details. +::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..10fa1ae9648 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +Wenn du auf die APIs des Identitätsanbieters (Identity Provider) zugreifen und Aktionen mit Benutzerautorisierung durchführen möchtest, muss Logto bestimmte API-Berechtigungen (Scopes) erhalten und Tokens speichern. + +1. Füge die erforderlichen Berechtigungen im Feld **scope** gemäß den obigen Anweisungen hinzu. +2. Aktiviere **Tokens für dauerhaften API-Zugriff speichern** im Logto OIDC Enterprise Connector. Logto speichert Zugangstokens (Access tokens) sicher im Secret Vault. +3. Für **Standard** OIDC-Identitätsanbieter (Identity Provider) muss der `offline_access` Scope enthalten sein, um ein Auffrischungstoken (Refresh token) zu erhalten und wiederholte Benutzerzustimmungsaufforderungen zu vermeiden. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..d4ed059ff00 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +Gib die `E-Mail-Domains` deiner Organisation im Tab `SSO-Erfahrung` des Logto-Connectors an. Dadurch wird der SSO-Connector als Authentifizierungsmethode für diese Benutzer aktiviert. + +Benutzer mit E-Mail-Adressen in den angegebenen Domains werden weitergeleitet, um deinen SSO-Connector als einzige Authentifizierungsmethode zu verwenden. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index 2a29c359206..b125720f906 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -4,38 +4,42 @@ sidebar_position: 2 # Bereitstellung und Konfiguration -Im vorherigen Artikel haben wir die Grundlagen des [schnellen Einstiegs mit Logto](/logto-oss/get-started-with-oss) behandelt. Dieser Artikel geht tiefer und konzentriert sich auf bewährte Praktiken und detaillierte Konfigurationsschritte für die Bereitstellung von Logto in einer Produktionsumgebung. +Im vorherigen Artikel haben wir die Grundlagen zum [schnellen Einstieg mit Logto](/logto-oss/get-started-with-oss) behandelt. Dieser Artikel geht einen Schritt weiter und konzentriert sich auf Best Practices und detaillierte Konfigurationsschritte für die Bereitstellung von Logto in einer Produktionsumgebung. ## Umgebungsvariablen \{#environment-variables} -Wir verwenden ein generiertes Preset von Umgebungsvariablen in unserem Demo (`docker-compose.yml`), das du durch deine eigenen ersetzen und die Konsistenz über mehrere Logto-Instanzen hinweg beibehalten solltest. +Wir verwenden ein generiertes Preset von Umgebungsvariablen in unserem Demo (`docker-compose.yml`), das du durch deine eigenen ersetzen und über mehrere Logto-Instanzen hinweg konsistent halten solltest. -Du kannst die Umgebungen direkt setzen oder eine `.env`-Datei im Stammverzeichnis des Logto-Projekts ablegen. Wenn du mit Docker testest, überprüfe das generierte `.env`-Image in `/etc/logto`. +Du kannst Umgebungsvariablen direkt setzen oder eine `.env`-Datei im Logto-Projektstamm ablegen. Wenn du mit Docker testest, schaue dir die vom Image generierte `.env` in `/etc/logto` an. ### Wesentliches \{#essentials} -- `DB_URL` Der [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) für die Logto-Datenbank. -- `PORT` Der Port, auf dem Logto hört. Standard `3001`. -- `ENDPOINT` Du kannst eine URL mit deiner benutzerdefinierten Domain für die Produktion angeben (z. B. `ENDPOINT=https://logto.domain.com`). Dies beeinflusst auch den Wert des [OIDC-Ausstelleridentifikators](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). +- `DB_URL` Die [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) für die Logto-Datenbank. +- `PORT` Der Port, auf dem Logto lauscht. Standard `3001`. +- `ENDPOINT` Du kannst eine URL mit deiner eigenen Domain für die Produktion angeben (z. B. `ENDPOINT=https://logto.domain.com`). Dies beeinflusst auch den Wert des [OIDC-Aussteller-Identifiers](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). **Admin-Konsole aktivieren** -- `ADMIN_PORT` Der Port, auf dem die Logto Admin-Konsole hört. Standard `3002`. -- `ADMIN_ENDPOINT` Du kannst eine URL mit deiner benutzerdefinierten Domain für die Produktion angeben (z. B. `ADMIN_ENDPOINT=https://admin.domain.com`). Dies beeinflusst auch den Wert der Umleitungs-URIs der Admin-Konsole. +- `ADMIN_PORT` Der Port, auf dem die Logto Admin-Konsole lauscht. Standard `3002`. +- `ADMIN_ENDPOINT` Du kannst eine URL mit deiner eigenen Domain für die Produktion angeben (z. B. `ADMIN_ENDPOINT=https://admin.domain.com`). Dies beeinflusst auch den Wert der Redirect-URIs der Admin-Konsole. **Admin-Konsole deaktivieren** -- `ADMIN_DISABLE_LOCALHOST` Setze es auf `1` oder `true`, um den Port für die Admin-Konsole zu schließen. Wenn `ADMIN_ENDPOINT` nicht gesetzt ist, wird die Admin-Konsole vollständig deaktiviert. +- `ADMIN_DISABLE_LOCALHOST` Setze dies auf `1` oder `true`, um den Port für die Admin-Konsole zu schließen. Wenn `ADMIN_ENDPOINT` nicht gesetzt ist, wird die Admin-Konsole vollständig deaktiviert. -Für weitere Details zu Umgebungsvariablen siehe [Konfiguration](/concepts/core-service/configuration/). +Weitere Details zu Umgebungsvariablen findest du unter [Konfiguration](/concepts/core-service/configuration/). + +**Secret Vault aktivieren** + +- Um den [Secret Vault](/secret-vault) zu nutzen, musst du `SECRET_VAULT_KEK` auf einen base64-codierten String deines Key Encryption Key (KEK) setzen. Dieser wird verwendet, um Data Encryption Keys (DEK) im Secret Vault zu verschlüsseln. AES-256 (32 Bytes) wird empfohlen. Beispiel: `crypto.randomBytes(32).toString('base64')`. ### HTTPS \{#https} -Du kannst Node.js verwenden, um HTTPS direkt bereitzustellen, oder einen HTTPS-Proxy / Balancer vor Node.js einrichten. Siehe [HTTPS aktivieren](/concepts/core-service/configuration/#enabling-https) für Details. +Du kannst Node.js direkt für HTTPS verwenden oder einen HTTPS-Proxy / Load Balancer vor Node.js einrichten. Siehe [HTTPS aktivieren](/concepts/core-service/configuration/#enabling-https) für Details. ### Reverse Proxy \{#reverse-proxy} -Wenn du einen Reverse Proxy auf deinem Server verwenden möchtest, zum Beispiel Nginx oder Apache, musst du die Ports 3001 und 3002 separat in deinen Proxy-Pass-Einstellungen zuordnen. Angenommen, du verwendest Nginx, dein Logto-Auth-Endpunkt läuft auf Port 3001 und deine Logto-Admin-Konsole läuft auf 3002, füge die folgende Konfiguration in nginx.conf ein: +Wenn du einen Reverse Proxy auf deinem Server verwenden möchtest, zum Beispiel Nginx oder Apache, musst du die Ports 3001 und 3002 separat in deinen Proxy-Pass-Einstellungen abbilden. Angenommen, du verwendest Nginx, dein Logto-Auth-Endpunkt läuft auf Port 3001 und deine Logto-Admin-Konsole läuft auf 3002, dann füge die folgende Konfiguration in nginx.conf ein: ``` server { @@ -87,17 +91,17 @@ Lade die Nginx-Konfiguration neu, um die neuesten Änderungen zu übernehmen: nginx -s reload ``` -Alles ist bereit. Öffne den Browser und besuche `https://admin.your-domain.com`, du solltest die Logto-Willkommensseite sehen können. +Jetzt ist alles bereit. Öffne den Browser und besuche `https://admin.your-domain.com`, du solltest die Logto-Willkommensseite sehen. ## Containerisierung \{#containerization} -Für die Produktion kannst du Docker verwenden, um Logto zu containerisieren. Du findest die Dockerfile im Stammverzeichnis des Projekts. Wenn du mehrere Instanzen von Logto ausführen möchtest, zum Beispiel Logto in einem Kubernetes-Cluster bereitstellen, gibt es einige zusätzliche Schritte, die du unternehmen musst. +Für die Produktion kannst du Docker verwenden, um Logto zu containerisieren. Die Dockerfile findest du im Stammverzeichnis des Projekts. Wenn du mehrere Instanzen von Logto ausführen möchtest, zum Beispiel Logto in einem Kubernetes-Cluster bereitstellen, gibt es einige zusätzliche Schritte, die du beachten musst. ### Gemeinsamer Connectors-Ordner \{#shared-connectors-folder} -Standardmäßig erstellt Logto einen `connectors`-Ordner im Stammverzeichnis des `core`-Ordners. Wir empfehlen, den Ordner zwischen mehreren Instanzen von Logto zu teilen. Du musst den Ordner `packages/core/connectors` in den Container einbinden und `npm run cli connector add -- --official` ausführen, um die Connectors bereitzustellen. +Standardmäßig erstellt Logto einen `connectors`-Ordner im Stammverzeichnis des `core`-Ordners. Wir empfehlen, diesen Ordner zwischen mehreren Instanzen von Logto zu teilen. Du musst den Ordner `packages/core/connectors` ins Container mounten und `npm run cli connector add -- --official` ausführen, um die Connectors bereitzustellen. -Hier ist ein minimales Beispiel für `deployment` für Kubernetes: +Hier ein minimales Beispiel für ein `deployment` in Kubernetes: ```yaml apiVersion: extensions/v1beta1 @@ -130,21 +134,21 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -In diesem Beispiel erstellen wir ein leeres Verzeichnis als Volume und binden es in Container ein. Dann führen wir `npm run cli connector add -- --official` im Init-Container aus, um die Connectors herunterzuladen. Schließlich teilt jeder Container denselben Connectors-Ordner mit unseren offiziellen Connectors, die bereits darin enthalten sind. +In diesem Beispiel erstellen wir ein leeres Verzeichnis als Volume und mounten es in die Container. Dann führen wir `npm run cli connector add -- --official` im Init-Container aus, um die Connectors herunterzuladen. Schließlich teilen sich alle Container denselben Connectors-Ordner mit unseren offiziellen Connectors darin. :::note -Dies ist ein Beispiel-YAML, um Logto auszuführen, musst du die Umgebungen richtig setzen. +Dies ist ein Beispiel-yaml. Um Logto auszuführen, musst du die Umgebungsvariablen korrekt setzen. ::: -Für die Produktion kannst du das "leere Verzeichnis"-Volume durch ein persistentes Volume ersetzen und den "Init"-Job auf deine eigene Weise durchführen, du weißt, was du tust! +Für die Produktion kannst du das "empty dir"-Volume durch ein Persistent Volume ersetzen und den "Init"-Job auf deine eigene Weise durchführen – du weißt, was du tust! -### Datenbankänderung \{#database-alteration} +### Datenbank-Änderung \{#database-alteration} -Ähnlich wie bei den Connectors muss die Datenbankänderung in einer einzelnen Instanz ausgeführt werden. Du kannst einen Job verwenden, um das Änderungsskript auszuführen. +Ähnlich wie bei den Connectors muss die Datenbank-Änderung in einer einzelnen Instanz ausgeführt werden. Du kannst einen Job verwenden, um das Änderungsskript auszuführen. -Die Umgebungsvariable `CI=true` ist notwendig, wenn die Änderung nicht interaktiv ausgeführt wird. +Die Umgebungsvariable `CI=true` ist notwendig, wenn die Änderung nicht-interaktiv ausgeführt wird. ```yaml apiVersion: batch/v1 @@ -171,4 +175,4 @@ spec: restartPolicy: Never ``` -Siehe [Datenbankänderung](/logto-oss/using-cli/database-alteration/) für Details zum Änderungskommando. +Siehe [Datenbank-Änderung](/logto-oss/using-cli/database-alteration/) für Details zum Änderungskommando. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..72010ab82fb --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# Secret Vault + +Der Secret Vault in Logto wurde entwickelt, um sensible Benutzerdaten wie Zugangstokens (Access tokens), API-Schlüssel, Zugangscodes oder andere vertrauliche Informationen, die Schutz benötigen, sicher zu speichern. Diese Geheimnisse werden häufig verwendet, um im Namen des Benutzers auf Drittanbieterdienste zuzugreifen, was eine sichere Speicherung unerlässlich macht. + +## Verschlüsselungsschema \{#encryption-scheme} + +Um sensible Daten zu schützen, verwendet der Secret Vault ein robustes Verschlüsselungsschema, das auf **Data Encryption Keys (DEK)** und **Key Encryption Keys (KEK)** basiert. + +- **Verschlüsselung pro Geheimnis:** Jedes Geheimnis wird mit einem eigenen, einzigartigen DEK verschlüsselt. Dadurch bleibt auch bei Kompromittierung eines Schlüssels der Schutz der anderen Geheimnisse erhalten. +- **Key Wrapping:** Der DEK selbst wird mit einem KEK verschlüsselt („gewrappt“), der vom System sicher verwaltet und gespeichert wird. +- **Mehrschichtige Sicherheit:** Dieser zweistufige Ansatz stellt sicher, dass selbst bei einem Teilbruch des Systems Angreifer ohne DEK und KEK keinen Zugriff auf die Geheimnisse erhalten. +- **Minimierte Exposition:** Geheimnisse werden nur dann entschlüsselt, wenn es absolut notwendig ist. Das reduziert das Risiko einer versehentlichen Offenlegung und entspricht den Best Practices im Umgang mit sensiblen Daten. + +Dieses mehrschichtige Verschlüsselungsmodell bietet starken Schutz für die sensibelsten Zugangsdaten und Tokens der Benutzer, ermöglicht aber dennoch bei Bedarf einen sicheren Zugriff. + +## Geheimnistypen \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +Derzeit ist das Federated token set der einzige unterstützte Geheimnistyp „out of the box“. Der Secret Vault ist jedoch so konzipiert, dass er jede Art von sensiblen Informationen aufnehmen kann. Wenn du Unterstützung für weitere Geheimnistypen benötigst, [kontaktiere uns bitte](https://logto.io/contact) — wir helfen dir gerne weiter. +::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/de/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..ac310bd1352 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: Föderiertes Token-Set +sidebar_label: Föderiertes Token-Set +--- + +import Availability from '@components/Availability'; + + + +Ein föderiertes Token-Set ist ein Geheimnistyp, der im Secret Vault von Logto gespeichert wird und dazu dient, Zugangstokens (Access tokens) und Auffrischungstokens (Refresh tokens), die von föderierten Drittanbieter-Identitätsanbietern ausgestellt wurden, sicher zu verwalten. Wenn sich ein Benutzer über einen Social- oder Enterprise-SSO-Connector authentifiziert, speichert Logto die ausgestellten Tokens im Vault. Diese Tokens können später abgerufen werden, um im Namen des Benutzers auf Drittanbieter-APIs zuzugreifen, ohne dass eine erneute Authentifizierung erforderlich ist. + +## Föderierte Token-Speicherung aktivieren \{#enable-federated-token-storage} + +### Social Connectors \{#social-connectors} + +:::Info +Diese Funktion ist nur für Connectors verfügbar, die die Token-Speicherung unterstützen. Derzeit unterstützte Connectors sind: [GitHub](/integrations/github), [Google](/integrations/google), [Facebook](/integrations/facebook), [Standard OAuth 2.0](/integrations/oauth2) und [Standard OIDC](/integrations/oidc). Die Unterstützung für weitere Connectors wird schrittweise eingeführt. +::: + +1. Navigiere zu Konsole > Connectors > Social Connectors. +2. Wähle den Social Connector aus, für den du die föderierte Token-Speicherung aktivieren möchtest. +3. Aktiviere auf der Seite „Einstellungen“ die Option **Tokens für persistierenden API-Zugriff speichern**. + +### Enterprise SSO Connectors \{#enterprise-sso-connectors} + +:::Info +Die Token-Speicherung ist für alle OIDC-Enterprise-Connectors verfügbar. +::: + +1. Navigiere zu Konsole > Enterprise SSO. +2. Wähle den Enterprise SSO Connector aus, für den du die föderierte Token-Speicherung aktivieren möchtest. +3. Aktiviere im Tab „SSO-Erfahrung“ die Option **Tokens für persistierenden API-Zugriff speichern**. + +Stelle sicher, dass du deine Änderungen speicherst. + +## Token-Speicherung \{#token-storage} + +Sobald die föderierte Token-Speicherung aktiviert ist, speichert Logto automatisch die Zugangstokens (Access tokens) und Auffrischungstokens (Refresh tokens), die vom föderierten Identitätsanbieter ausgestellt werden, wann immer sich ein Benutzer über einen Social- oder Enterprise-SSO-Connector authentifiziert. Dies umfasst: + +- [Soziale Anmeldung und Registrierung](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [Enterprise SSO Anmeldung und Registrierung](/end-user-flows/enterprise-sso) +- [Verknüpfung sozialer Konten über Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +Die gespeicherten Tokens sind mit der Social- oder Enterprise-SSO-Identität des Benutzers verknüpft, sodass sie später für den API-Zugriff abgerufen werden können, ohne dass eine erneute Authentifizierung erforderlich ist. + +### Überprüfung des Token-Speicherstatus \{#checking-token-storage-status} + +Du kannst den Status der föderierten Token-Speicherung eines Benutzers in der Logto-Konsole überprüfen: + +1. Navigiere zu Konsole > Benutzer. +2. Klicke auf den Benutzer, den du überprüfen möchtest. Dadurch gelangst du zur Detailseite des Benutzers. +3. Scrolle zum Abschnitt **Verbindungen**. Dieser Bereich listet alle Social- und Enterprise-SSO-Verbindungen auf, die mit dem Benutzer verknüpft sind. +4. Jeder Eintrag zeigt ein Token-Status-Label an, das angibt, ob Tokens für diese Verbindung gespeichert sind. +5. Klicke auf den Verbindungseintrag, um weitere Details anzuzeigen, einschließlich der Metadaten des gespeicherten Zugangstokens und der Verfügbarkeit eines Auffrischungstokens (falls vorhanden). + +Du kannst auch die Drittanbieter-Identitäten eines Benutzers und den Token-Speicherstatus über die Management API überprüfen: + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`: Ruft die Social-Identität eines Benutzers und den Token-Speicherstatus ab, der mit der Identität durch einen bestimmten Connector-Target (z. B. `github`, `google` usw.) verknüpft ist. +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`: Ruft die Enterprise-SSO-Identität eines Benutzers und den Token-Speicherstatus ab, der mit der Identität durch eine bestimmte SSO-Connector-ID verknüpft ist. + +### Token-Speicherstatus \{#token-storage-status} + +- **Aktiv**: Das Zugangstoken ist gespeichert und aktiv. +- **Abgelaufen**: Das Zugangstoken ist gespeichert, aber abgelaufen. Wenn ein Auffrischungstoken verfügbar ist, kann damit ein neues Zugangstoken abgerufen werden. +- **Inaktiv**: Für diese Verbindung ist kein Zugangstoken gespeichert. Dies kann passieren, wenn sich der Benutzer nicht über diese Verbindung authentifiziert hat oder die Token-Speicherung gelöscht wurde. +- **Nicht anwendbar**: Der Connector unterstützt keine Token-Speicherung. + +### Token-Metadaten \{#token-metadata} + +Zur Wahrung der Datenintegrität und Sicherheit werden alle Tokens vor der Speicherung im Secret Vault verschlüsselt. Die tatsächlichen Token-Werte sind nur für den Endbenutzer mit entsprechender Autorisierung zugänglich. Entwickler können hingegen nur die Metadaten des Token-Sets abrufen, um den Zustand der gespeicherten Tokens zu verstehen, ohne sensible Inhalte offenzulegen. + +- `createdAt`: Der Zeitstempel, zu dem die Verbindung erstmals hergestellt und das Token-Set initial im Secret Vault gespeichert wurde. +- `updatedAt`: Das letzte Mal, als das Token-Set aktualisiert wurde. + - Wenn kein Auffrischungstoken verfügbar ist, entspricht dieser Wert **createdAt**. + - Wenn ein Auffrischungstoken vorhanden ist, spiegelt dieser Wert den letzten Zeitpunkt wider, zu dem das Zugangstoken aufgefrischt wurde. +- `hasRefreshToken`: Gibt an, ob ein Auffrischungstoken verfügbar ist. + Wenn der Connector Offline-Zugriff unterstützt und die Autorisierungsanfrage entsprechend konfiguriert ist, speichert Logto das Auffrischungstoken, wenn es vom Identitätsanbieter zusammen mit dem Zugangstoken ausgestellt wird. + Wenn das Zugangstoken abläuft und ein gültiges Auffrischungstoken existiert, versucht Logto automatisch, ein neues Zugangstoken mit dem gespeicherten Auffrischungstoken zu erhalten, wann immer der Benutzer Zugriff auf den verbundenen Anbieter anfordert. +- `expiresAt`: Die geschätzte Ablaufzeit des Zugangstokens in **Sekunden**. + Dies wird basierend auf dem Wert `expires_in` berechnet, der vom Token-Endpunkt des Identitätsanbieters zurückgegeben wird. (Dieses Feld ist nur verfügbar, wenn der Anbieter `expires_in` in der Token-Antwort enthält.) +- `scope`: Die Berechtigung (Scope) des Zugangstokens, die die vom Identitätsanbieter gewährten Berechtigungen angibt. + Dies ist nützlich, um zu verstehen, welche Aktionen mit dem gespeicherten Zugangstoken durchgeführt werden können. (Dieses Feld ist nur verfügbar, wenn der Anbieter `scope` in der Token-Antwort enthält.) +- `tokenType`: Der Typ des Zugangstokens, typischerweise „Bearer“. + (Dieses Feld ist nur verfügbar, wenn der Anbieter `token_type` in der Token-Antwort enthält.) + +## Token-Abruf \{#token-retrieval} + +Sobald die Token-Speicherung aktiviert und Tokens sicher im Secret Vault von Logto gespeichert sind, können Endbenutzer ihre Drittanbieter-Zugangstokens aus deiner Client-Anwendung abrufen, indem sie die [User Account API](/end-user-flows/account-settings/by-account-api) von Logto integrieren. + +- `GET /my-account/identities/:target/access-token`: Ruft das Zugangstoken für eine Social-Identität ab, indem der Connector-Target angegeben wird (z. B. github, google). + +- `GET /my-account/sso-identities/:connectorId/access-token`: Ruft das Zugangstoken für eine Enterprise-SSO-Identität ab, indem die Connector-ID angegeben wird. + +:::info +Erfahre, wie du die [Account API aktivierst](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) und [auf die Account API mit dem von Logto ausgestellten Zugangstoken zugreifst](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token). +::: + +### Token-Rotation \{#token-rotation} + +Die Token-Abruf-Endpunkte liefern: + +- `200` OK: Wenn das Zugangstoken erfolgreich abgerufen wurde und noch gültig ist. +- `404` Nicht gefunden: Wenn der Benutzer keine Social- oder Enterprise-SSO-Identität mit dem angegebenen Target oder der Connector-ID verknüpft hat oder das Zugangstoken nicht gespeichert ist. +- `401` Nicht autorisiert: Wenn das Zugangstoken abgelaufen ist. + +Wenn das Zugangstoken abgelaufen ist und ein Auffrischungstoken verfügbar ist, versucht Logto automatisch, das Zugangstoken zu erneuern und gibt das neue Zugangstoken in der Antwort zurück. Die Token-Speicherung im Secret Vault wird ebenfalls mit dem neuen Zugangstoken und dessen Metadaten aktualisiert. + +## Token-Speicherung löschen \{#token-storage-deletion} + +Die föderierte Token-Speicherung ist direkt mit den Social- oder Enterprise-SSO-Verbindungen jedes Benutzers verknüpft. Das bedeutet, dass das gespeicherte Token-Set in folgenden Fällen automatisch gelöscht wird: + +- Die zugehörige Social- oder Enterprise-SSO-Identität wird aus dem Benutzerkonto entfernt. +- Das Benutzerkonto wird aus deinem Mandanten gelöscht. +- Der Social- oder Enterprise-SSO-Connector wird aus deinem Mandanten gelöscht. + +### Tokens widerrufen \{#revoking-tokens} + +Du kannst das Drittanbieter-Token-Set eines Benutzers auch manuell löschen, um den Zugriff zu widerrufen: + +- Über die Konsole: + Navigiere zur Identitätsdetailseite des Benutzers. Scrolle zum Abschnitt **Zugangstoken** (falls Token-Speicherung verfügbar ist) und klicke am Ende des Abschnitts auf die Schaltfläche **Tokens löschen**. +- Über die Management API: + - `DELETE /api/secret/:id`: Löscht ein bestimmtes Geheimnis anhand seiner ID, die du aus den Identitätsdetails des Benutzers erhältst. + +Das Widerrufen des Token-Sets zwingt den Benutzer, sich erneut beim Drittanbieter zu authentifizieren, um ein neues Zugangstoken zu erhalten, bevor er wieder auf Drittanbieter-APIs zugreifen kann. + +## Erneute Authentifizierung und Token-Erneuerung \{#reauthentication-and-token-renewal} + +In Szenarien, in denen ein gespeichertes Zugangstoken abgelaufen ist oder eine Anwendung zusätzliche API-Berechtigungen anfordern muss, können Endbenutzer sich beim Drittanbieter erneut authentifizieren, um ein neues Zugangstoken zu erhalten – ohne sich erneut bei Logto anmelden zu müssen. +Dies kann über die [Social Verification API](https://openapi.logto.io/operation/operation-createverificationbysocial) von Logto erfolgen, die es Benutzern ermöglicht, einen föderierten Social-Autorisierungsfluss erneut zu starten und ihr gespeichertes Token-Set zu aktualisieren. + +:::note +Das erneute Initiieren der föderierten Autorisierung ist derzeit auf Social Connectors beschränkt. +Für Enterprise-SSO-Connectors erfordern erneute Authentifizierung und Token-Erneuerung, dass der Benutzer erneut einen vollständigen Logto-Authentifizierungsfluss durchläuft, da eine direkte Re-Autorisierung mit dem Enterprise-SSO-Anbieter nach der Anmeldung derzeit nicht unterstützt wird. +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as Benutzer + participant Logto as Logto + participant Provider as Drittanbieter + + User->>Logto: post /api/verification/social + Logto->>User: Weiterleitung zum Drittanbieter + User->>Provider: Authentifizieren und autorisieren + Provider->>User: Weiterleitung zurück mit Autorisierungscode + User->>Logto: post /api/verification/social/verify mit Autorisierungscode + Logto->>User: Rückgabe der Social Verification ID + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. Der Benutzer startet eine Social Verification-Anfrage, indem er den Endpunkt `POST /api/verification/social` aufruft. Der Benutzer kann benutzerdefinierte Berechtigungen (Scopes) angeben, um zusätzliche Berechtigungen vom Drittanbieter anzufordern. + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**: Das vom Logto ausgestellte Zugangstoken des Benutzers. + - **connectorId**: Die Social Connector ID in Logto. + - **redirectUri**: Die URI, zu der der Benutzer nach der Authentifizierung zurück zu deiner Anwendung geleitet wird. Du musst diese URI in den Anwendungseinstellungen des Anbieters registrieren. + - **scope**: (Optional) Benutzerdefinierte Berechtigungen, um zusätzliche Rechte vom Drittanbieter anzufordern. Wenn nicht angegeben, werden die in dem Connector konfigurierten Standard-Berechtigungen verwendet. + +2. Logto erstellt einen neuen Social Verification-Datensatz und gibt die Social Verification ID zusammen mit der Autorisierungs-URL zurück, um den Benutzer zum Drittanbieter zur Authentifizierung weiterzuleiten. + + Die Antwort sieht wie folgt aus: + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. Leite den Benutzer zur Autorisierungs-URL weiter. Der Benutzer authentifiziert sich beim Drittanbieter und gewährt Berechtigungen. + +4. Der Drittanbieter leitet den Benutzer mit einem Autorisierungscode zurück zu deiner Client-Anwendung. + +5. Verarbeite den Autorisierungs-Callback, indem du den Autorisierungscode an den Verification-Endpunkt von Logto weiterleitest: + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**: Das vom Logto ausgestellte Zugangstoken des Benutzers. + - **verificationRecordId**: Die Social Verification ID aus dem vorherigen Schritt. + - **connectorData**: Der Autorisierungscode und alle weiteren Daten, die vom Drittanbieter beim Callback zurückgegeben wurden. + + :::note + Vergiss nicht, den `state`-Parameter zu validieren, um CSRF-Angriffe zu verhindern. + ::: + +6. Logto überprüft den Autorisierungscode und tauscht ihn gegen ein neues Zugangstoken und Auffrischungstoken vom Drittanbieter aus und gibt dann die Social Verification ID in der Antwort zurück. + +7. Aktualisiere abschließend die Token-Speicherung des Benutzers, indem du den Endpunkt `PATCH /my-account/identities/:target/access-token` mit der Social Verification ID aufrufst: + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**: Das vom Logto ausgestellte Zugangstoken des Benutzers. + - **socialVerificationId**: Die verifizierte Social Verification Record ID aus dem vorherigen Schritt. + + Dadurch wird das Token-Set des Benutzers im Secret Vault von Logto mit dem neuen Zugangstoken und Auffrischungstoken aktualisiert, sodass der Benutzer auf Drittanbieter-APIs zugreifen kann, ohne sich erneut bei Logto anmelden zu müssen. + + Das aktualisierte Zugangstoken wird zurückgegeben. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/de/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index d19c11a77f7..363f5416510 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -10,7 +10,7 @@ Persönliche Zugriffstokens (PATs) bieten eine sichere Möglichkeit für Benutze ### Über die Konsole \{#using-console} -Du kannst persönliche Zugriffstokens auf der Seite "Benutzerdetails" der Konsole > Benutzerverwaltung verwalten. In der Karte "Authentifizierung (Authentication)" siehst du die Liste der persönlichen Zugriffstokens und kannst neue erstellen. +Du kannst persönliche Zugriffstokens auf der Seite „Benutzerdetails“ der Konsole > Benutzerverwaltung verwalten. In der Karte „Authentifizierung (Authentication)“ siehst du die Liste der persönlichen Zugriffstokens und kannst neue erstellen. ### Über die Management API \{#using-management-api} @@ -18,24 +18,36 @@ Nach dem Einrichten der [Management API](/integrate-logto/interact-with-manageme ## PATs verwenden, um Zugangstokens zu gewähren \{#use-pats-to-grant-access-tokens} -Nach dem Erstellen eines PAT kannst du ihn verwenden, um Zugangstokens für deine Anwendung über den Token-Austausch-Endpunkt zu gewähren. +Nach dem Erstellen eines PAT kannst du diesen verwenden, um deiner Anwendung Zugangstokens über den Token-Exchange-Endpunkt zu gewähren. + +:::tip Tokenfluss-Äquivalenz + +Mit PATs erhaltene Zugangstokens funktionieren **identisch** wie Tokens, die über den Standard-`refresh_token`-Flow erhalten werden. Das bedeutet: + +- **Organisationskontext**: Über PATs erhaltene Tokens unterstützen die gleichen Organisationsberechtigungen und Berechtigungen (Scopes) wie Refresh-Token-Flows +- **Autorisierungsfluss**: Du kannst PAT-ausgetauschte Zugangstokens für [Organisationsberechtigungen](/authorization/organization-permissions) und [organisationsbezogene API-Ressourcen](/authorization/organization-level-api-resources) verwenden +- **Tokenvalidierung**: Die gleiche Validierungslogik gilt – nur der anfängliche Grant-Typ unterscheidet sich + +Wenn du mit Organisationen arbeitest, sind die Zugriffsmuster und Berechtigungen gleich, unabhängig davon, ob du PAT oder Auffrischungstokens verwendest. + +::: ### Anfrage \{#request} -Die Anwendung stellt eine [Token-Austauschanfrage](https://auth.wiki/authorization-code-flow#token-exchange-request) an den [Token-Endpunkt](/integrate-logto/application-data-structure#token-endpoint) des Tenants mit einem speziellen Grant-Typ über die HTTP-POST-Methode. Die folgenden Parameter sind im HTTP-Request-Entity-Body im `application/x-www-form-urlencoded`-Format enthalten. +Die Anwendung stellt eine [Token-Exchange-Anfrage](https://auth.wiki/authorization-code-flow#token-exchange-request) an den [Token-Endpunkt](/integrate-logto/application-data-structure#token-endpoint) des Tenants mit einem speziellen Grant-Typ über die HTTP-POST-Methode. Die folgenden Parameter werden im HTTP-Request-Entity-Body im Format `application/x-www-form-urlencoded` übergeben. 1. `client_id`: ERFORDERLICH. Die Client-ID der Anwendung. 2. `grant_type`: ERFORDERLICH. Der Wert dieses Parameters muss `urn:ietf:params:oauth:grant-type:token-exchange` sein und zeigt an, dass ein Token-Austausch durchgeführt wird. 3. `resource`: OPTIONAL. Der Ressourcenindikator, wie bei anderen Token-Anfragen. 4. `scope`: OPTIONAL. Die angeforderten Berechtigungen (Scopes), wie bei anderen Token-Anfragen. 5. `subject_token`: ERFORDERLICH. Das PAT des Benutzers. -6. `subject_token_type`: ERFORDERLICH. Der Typ des Sicherheitstokens, das im Parameter `subject_token` bereitgestellt wird. Der Wert dieses Parameters muss `urn:logto:token-type:personal_access_token` sein. +6. `subject_token_type`: ERFORDERLICH. Der Typ des im Parameter `subject_token` bereitgestellten Sicherheitstokens. Der Wert dieses Parameters muss `urn:logto:token-type:personal_access_token` sein. ### Antwort \{#response} -Wenn die Token-Austauschanfrage erfolgreich ist, gibt der Token-Endpunkt des Tenants einen Zugangstoken zurück, das die Identität des Benutzers repräsentiert. Die Antwort enthält die folgenden Parameter im HTTP-Response-Entity-Body im `application/json`-Format. +Wenn die Token-Exchange-Anfrage erfolgreich ist, gibt der Token-Endpunkt des Tenants einen Zugangstoken zurück, der die Identität des Benutzers repräsentiert. Die Antwort enthält die folgenden Parameter im HTTP-Response-Entity-Body im Format `application/json`. -1. `access_token`: ERFORDERLICH. Das Zugangstoken des Benutzers, wie bei anderen Token-Anfragen wie `authorization_code` oder `refresh_token`. +1. `access_token`: ERFORDERLICH. Der Zugangstoken des Benutzers, wie bei anderen Token-Anfragen wie `authorization_code` oder `refresh_token`. 2. `issued_token_type`: ERFORDERLICH. Der Typ des ausgegebenen Tokens. Der Wert dieses Parameters muss `urn:ietf:params:oauth:token-type:access_token` sein. 3. `token_type`: ERFORDERLICH. Der Typ des Tokens. Der Wert dieses Parameters muss `Bearer` sein. 4. `expires_in`: ERFORDERLICH. Die Lebensdauer des Zugangstokens in Sekunden. @@ -68,7 +80,7 @@ Content-Type: application/json } ``` -Das Beispiel-Zugangstoken-Payload: +Das Beispiel-Payload des Zugangstokens: ```json { @@ -90,5 +102,5 @@ Das Beispiel-Zugangstoken-Payload: Persönliche Zugriffstokens, Maschine-zu-Maschine-Authentifizierung und API-Schlüssel: Definition - und ihre Anwendungsfälle in der Praxis + und reale Anwendungsfälle diff --git a/i18n/de/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/de/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index 39c749032a4..3130fe2367b 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -10,7 +10,7 @@ Logto unterstützt die manuelle Migration bestehender Benutzer von einer anderen Bevor wir beginnen, werfen wir einen Blick auf das [Benutzerschema](/user-management/user-data/#user-profile) in Logto. Es gibt 3 Teile des Benutzerschemas, die du kennen solltest: -1. **Basisdaten**: Dies sind die Basisinformationen aus dem Benutzerprofil. Du kannst die Daten aus deinem bestehenden Benutzerprofil zuordnen. +1. **Basisdaten**: Dies sind die grundlegenden Informationen aus dem Benutzerprofil. Du kannst die Daten aus deinem bestehenden Benutzerprofil zuordnen. 2. **Benutzerdefinierte Daten**: Speichert zusätzliche Benutzerinformationen. Du kannst dies verwenden, um Felder zu speichern, die nicht den Basisdaten zugeordnet werden können. 3. **Soziale Identitäten**: Speichert die Benutzerinformationen, die durch Social Sign-In abgerufen wurden. @@ -18,9 +18,11 @@ Du kannst eine Zuordnung erstellen, um die Benutzerinformationen aus deinem best ## Passwort-Hashing \{#password-hashing} -Logto verwendet [Argon2](https://de.wikipedia.org/wiki/Argon2), um das Passwort des Benutzers zu hashen, und unterstützt außerdem andere Algorithmen wie `MD5`, `SHA1`, `SHA256` und `Bcrypt` zur Erleichterung der Migration. Diese Algorithmen gelten als unsicher; die entsprechenden Passwort-Hashes werden beim ersten erfolgreichen Anmelden des Benutzers auf Argon2 migriert. +Logto verwendet [Argon2](https://de.wikipedia.org/wiki/Argon2) zum Hashen des Benutzerpassworts und unterstützt zur Erleichterung der Migration auch andere Algorithmen wie `MD5`, `SHA1`, `SHA256` und `Bcrypt`. Diese Algorithmen gelten als unsicher; die entsprechenden Passwort-Hashes werden beim ersten erfolgreichen Anmelden des Benutzers auf Argon2 migriert. -Wenn du andere Hashing-Algorithmen oder Salt verwendest, kannst du `passwordAlgorithm` auf `Legacy` setzen. Dadurch kannst du jeden von Node.js unterstützten Hash-Algorithmus verwenden. Die Liste der unterstützten Algorithmen findest du in der [Node.js Crypto-Dokumentation](https://nodejs.org/api/crypto.html#cryptogethashes). In diesem Fall ist das `passwordDigest` ein JSON-String, der den Hash-Algorithmus und andere algorithmusspezifische Parameter enthält. +Wenn du andere Hashing-Algorithmen oder Salt verwendest, kannst du `passwordAlgorithm` auf `Legacy` setzen. Dadurch kannst du jeden von Node.js unterstützten Hash-Algorithmus verwenden. Die Liste der unterstützten Algorithmen findest du in der [Node.js Crypto-Dokumentation](https://nodejs.org/api/crypto.html#cryptogethashes). In diesem Fall ist `passwordDigest` ein JSON-String, der den Hash-Algorithmus und andere algorithmusspezifische Parameter enthält. + +### Allgemeines Legacy-Format \{#general-legacy-format} Das Format des JSON-Strings ist wie folgt: @@ -44,6 +46,36 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### PBKDF2-Unterstützung \{#pbkdf2-support} + +Logto unterstützt speziell [PBKDF2](https://de.wikipedia.org/wiki/PBKDF2). + +Um mit PBKDF2 gehashte Passwörter zu migrieren, setze `passwordAlgorithm` auf `Legacy` und formatiere den `passwordDigest` wie folgt: + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +Die Parameter sind: + +- **`salt`**: Der im ursprünglichen Hashing verwendete Salt-Wert +- **`iterations`**: Anzahl der Iterationen (z. B. `"1000"`) +- **`keylen`**: Länge des abgeleiteten Schlüssels in Bytes (z. B. `"20"`) +- **`digest`**: Die verwendete Hash-Funktion (z. B. `"sha512"`, `"sha256"`, `"sha1"`) +- **`@`**: Platzhalter für den tatsächlichen Passwortwert +- **`expected_hashed_value`**: Das erwartete Hash-Ergebnis als Hexadezimal-String + +**Beispiel für ein Migrations-Payload:** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## Schritte zur Migration \{#steps-to-migrate} 1. **Benutzerdaten vorbereiten** @@ -96,9 +128,9 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -Bitte beachte, dass der API-Endpunkt einer Rate-Limitierung unterliegt. Du solltest zwischen den einzelnen Anfragen eine Pause einlegen, um das Rate Limit nicht zu überschreiten. Siehe unsere Seite zu [Rate Limits](/integrate-logto/interact-with-management-api/#rate-limit) für Details. +Bitte beachte, dass der API-Endpunkt einer Rate-Limitierung unterliegt. Du solltest zwischen den einzelnen Anfragen eine Pause einbauen, um das Rate-Limit nicht zu überschreiten. Siehe unsere Seite zu [Rate Limits](/integrate-logto/interact-with-management-api/#rate-limit) für Details. -Wenn du eine große Menge an Benutzerdaten hast (100.000+ Benutzer), kannst du [uns kontaktieren](https://logto.io/contact), um das Rate Limit zu erhöhen. +Wenn du eine große Menge an Benutzerdaten (100k+ Benutzer) hast, kannst du [uns kontaktieren](https://logto.io/contact), um das Rate-Limit zu erhöhen. ## Verwandte Ressourcen \{#related-resources} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/es/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index 8d1b9d7d243..40cc4195dce 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -4,7 +4,7 @@ ### Uso {#usage} -Logto maneja las variables de entorno en el siguiente orden: +Logto gestiona las variables de entorno en el siguiente orden: - Variables de entorno del sistema - El archivo `.env` en la raíz del proyecto, que cumple con el formato [dotenv](https://github.com/motdotla/dotenv#readme) @@ -14,53 +14,54 @@ Por lo tanto, las variables de entorno del sistema sobrescribirán los valores e ### Variables {#variables} :::caution -Si ejecutas Logto a través de `npm start` en la raíz del proyecto, `NODE_ENV` siempre será `production`. +Si ejecutas Logto mediante `npm start` en la raíz del proyecto, `NODE_ENV` siempre será `production`. ::: En los valores predeterminados, `protocol` será `http` o `https` según tu configuración de HTTPS. -| Clave | Valor Predeterminado | Tipo | Descripción | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Qué tipo de entorno en el que se ejecuta Logto. | -| PORT | `3001` | `number` | El puerto local al que Logto escucha. | -| ADMIN_PORT | `3002` | `number` | El puerto local al que escucha Logto Admin Console. | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Establécelo en `1` o `true` para deshabilitar el puerto para Admin Console. Con `ADMIN_ENDPOINT` sin establecer, deshabilitará completamente Admin Console. | -| DB_URL | N/A | `string` | El [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para la base de datos de Logto. | -| HTTPS_CERT_PATH | `undefined` | string | undefined | Consulta [Habilitar HTTPS](#enabling-https) para más detalles. | -| HTTPS_KEY_PATH | `undefined` | string | undefined | Ídem. | -| TRUST_PROXY_HEADER | `false` | `boolean` | Ídem. | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Puedes especificar una URL con tu dominio personalizado para pruebas en línea o producción. Esto también afectará el valor del [identificador del emisor de OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Puedes especificar una URL con tu dominio personalizado para producción (Ej. `ADMIN_ENDPOINT=https://admin.domain.com`). Esto también afectará el valor de los URIs de redirección de Admin Console. | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Especifica si el nombre de usuario distingue entre mayúsculas y minúsculas. Ten cuidado al modificar este valor; los cambios no ajustarán automáticamente los datos existentes de la base de datos, requiriendo gestión manual. | +| Key | Valor predeterminado | Tipo | Descripción | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Qué tipo de entorno ejecuta Logto. | +| PORT | `3001` | `number` | El puerto local en el que Logto escucha. | +| ADMIN_PORT | `3002` | `number` | El puerto local en el que escucha la Consola de Administración de Logto. | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Establécelo en `1` o `true` para deshabilitar el puerto de la Consola de Administración. Si `ADMIN_ENDPOINT` no está configurado, deshabilitará completamente la Consola de Administración. | +| DB_URL | N/A | `string` | El [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para la base de datos de Logto. | +| HTTPS_CERT_PATH | `undefined` | string | undefined | Consulta [Habilitar HTTPS](#enabling-https) para más detalles. | +| HTTPS_KEY_PATH | `undefined` | string | undefined | Ídem. | +| TRUST_PROXY_HEADER | `false` | `boolean` | Ídem. | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Puedes especificar una URL con tu dominio personalizado para pruebas en línea o producción. Esto también afectará el valor del [identificador de emisor OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Puedes especificar una URL con tu dominio personalizado para producción (Ej. `ADMIN_ENDPOINT=https://admin.domain.com`). Esto también afectará el valor de los URI de redirección de la Consola de Administración. | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Especifica si el nombre de usuario distingue entre mayúsculas y minúsculas. Ten cuidado al modificar este valor; los cambios no ajustarán automáticamente los datos existentes en la base de datos, requiriendo gestión manual. | +| SECRET_VAULT_KEK | `undefined` | `string` | La Clave de Cifrado de Claves (KEK) utilizada para cifrar las Claves de Cifrado de Datos (DEK) en el [Secret Vault](/secret-vault). Requerida para que el Secret Vault funcione correctamente. Debe ser una cadena codificada en base64. Se recomienda AES-256 (32 bytes). Ejemplo: `crypto.randomBytes(32).toString('base64')` | ### Habilitar HTTPS {#enabling-https} #### Usando Node {#using-node} -Node admite HTTPS de forma nativa. Proporciona **AMBOS** `HTTPS_CERT_PATH` y `HTTPS_KEY_PATH` para habilitar HTTPS a través de Node. +Node admite HTTPS de forma nativa. Proporciona **AMBOS** `HTTPS_CERT_PATH` y `HTTPS_KEY_PATH` para habilitar HTTPS mediante Node. -`HTTPS_CERT_PATH` implica la ruta a tu certificado HTTPS, mientras que `HTTPS_KEY_PATH` implica la ruta a tu clave HTTPS. +`HTTPS_CERT_PATH` indica la ruta a tu certificado HTTPS, mientras que `HTTPS_KEY_PATH` indica la ruta a tu clave HTTPS. #### Usando un proxy HTTPS {#using-a-https-proxy} -Otra práctica común es tener un proxy HTTPS frente a Node (Ej. Nginx). +Otra práctica común es tener un proxy HTTPS delante de Node (Ej. Nginx). -En este caso, probablemente querrás establecer `TRUST_PROXY_HEADER` en `true`, lo que indica si los campos de encabezado del proxy deben ser confiables. Logto pasará el valor a [configuraciones de la aplicación Koa](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). +En este caso, probablemente querrás establecer `TRUST_PROXY_HEADER` en `true`, lo que indica si se deben confiar los campos de cabecera del proxy. Logto pasará el valor a la [configuración de la app Koa](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). -Consulta [Confiar en proxies de descarga de TLS](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) para saber cuándo configurar este campo. +Consulta [Confiar en proxies de descarga TLS](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) para saber cuándo configurar este campo. -## Configuraciones de la base de datos {#database-configs} +## Configuraciones de base de datos {#database-configs} -Gestionar demasiadas variables de entorno no es eficiente ni flexible, por lo que la mayoría de nuestras configuraciones generales se almacenan en la tabla de la base de datos `logto_configs`. +Gestionar demasiadas variables de entorno no es eficiente ni flexible, por lo que la mayoría de nuestras configuraciones generales se almacenan en la tabla de base de datos `logto_configs`. -La tabla es un almacenamiento simple de clave-valor, y la clave es enumerable de la siguiente manera: +La tabla es un almacenamiento simple de clave-valor, y la clave es enumerable como sigue: -| Clave | Tipo | Descripción | -| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| oidc.cookieKeys | string[] | El arreglo de cadenas de las [claves de firma de cookies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | -| oidc.privateKeys | string[] | El arreglo de cadenas del contenido de la clave privada para la [firma de JWT de OIDC](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | +| Key | Tipo | Descripción | +| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| oidc.cookieKeys | string[] | El array de cadenas de las [claves de firma de cookies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | +| oidc.privateKeys | string[] | El array de cadenas del contenido de la clave privada para la [firma JWT de OIDC](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | -### Tipos de clave privada compatibles {#supported-private-key-types} +### Tipos de clave privada admitidos {#supported-private-key-types} - EC (curvas P-256, secp256k1, P-384 y P-521) - RSA diff --git a/i18n/es/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/es/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index ebbe859aada..e3413712372 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -98,12 +98,13 @@ Ten en cuenta las siguientes configuraciones: - **Dominios de correo electrónico**: Si el dominio del correo electrónico ingresado por el usuario está en el campo "Dominios de correo electrónico empresarial" de algún conector SSO empresarial, el usuario será redirigido a la URL de inicio de sesión correspondiente de ese conector SSO. :::note - Es importante tener en cuenta que después de configurar los dominios de correo electrónico relevantes en un conector SSO, los usuarios que inicien sesión con correos electrónicos pertenecientes a esos dominios estarán obligados a usar el [inicio de sesión SSO](/end-user-flows/enterprise-sso). + Es importante tener en cuenta que después de configurar los dominios de correo electrónico relevantes en un conector SSO, los usuarios que inicien sesión con correos electrónicos pertenecientes a esos dominios se verán obligados a usar el [inicio de sesión SSO](/end-user-flows/enterprise-sso). En otras palabras, solo los correos electrónicos de dominios que NO estén configurados en los conectores SSO pueden usar el inicio de sesión "correo electrónico + código de verificación" o "correo electrónico + contraseña" (siempre que estos dos métodos de inicio de sesión estén habilitados en la experiencia de inicio de sesión). ::: - **Sincronizar perfiles de usuario**: Elige cuándo sincronizar la información del perfil del usuario (por ejemplo, avatar, nombre). El comportamiento predeterminado es "Sincronizar solo en el primer inicio de sesión". "Sincronizar siempre en cada inicio de sesión" es otra opción para este campo, pero puede provocar la sobrescritura de datos personalizados del usuario. +- **Habilitar almacenamiento de tokens**: Para los conectores empresariales OIDC, puedes habilitar el almacenamiento de tokens para guardar de forma segura los tokens de acceso y actualización en el [Secret Vault](/secret-vault) de Logto cuando los usuarios inicien sesión con un IdP empresarial. Esto permite que tu aplicación acceda a APIs de terceros en nombre del usuario sin requerir que se autentique nuevamente. Aprende más sobre el [almacenamiento federado de tokens](/secret-vault/federated-token-set). - **Información de visualización**: Opcionalmente, personaliza el nombre para mostrar y el logotipo del conector. Esto es muy útil cuando varios conectores están asociados al mismo dominio de correo electrónico. Los usuarios seleccionarán el IdP deseado de una lista de botones de conectores SSO antes de ser redirigidos a la página de inicio de sesión del IdP. ## Habilitar SSO empresarial \{#enabling-enterprise-sso} @@ -112,13 +113,13 @@ Ten en cuenta las siguientes configuraciones: 2. Activa el interruptor "SSO empresarial". 3. Guarda los cambios. -Una vez habilitado, aparecerá un botón de "Inicio de sesión único" en tu página de inicio de sesión. Los usuarios empresariales con dominios de correo electrónico habilitados para SSO podrán acceder a tus servicios utilizando sus proveedores de identidad empresarial (IdP). Para obtener más información sobre la experiencia de usuario de SSO, consulta Flujos de usuario: [SSO empresarial](/end-user-flows/enterprise-sso). +Una vez habilitado, aparecerá un botón de "Inicio de sesión único" en tu página de inicio de sesión. Los usuarios empresariales con dominios de correo electrónico habilitados para SSO pueden acceder a tus servicios utilizando sus proveedores de identidad empresarial (IdPs). Para obtener más información sobre la experiencia de usuario de SSO, consulta Flujos de usuario: [SSO empresarial](/end-user-flows/enterprise-sso). -## Just-in-time a organización \{#just-in-time-to-organization} +## Just-in-time a la organización \{#just-in-time-to-organization} En Logto, el [aprovisionamiento Just-in-Time (JIT)](https://auth.wiki/jit-provisioning) es un proceso utilizado para asignar automáticamente membresías y roles de organización a los usuarios en el momento en que inician sesión en el sistema por primera vez. -Logto proporciona un punto de entrada para configurar el aprovisionamiento JIT del conector SSO dentro de una organización, consulta la [referencia](/organizations/just-in-time-provisioning). +Logto proporciona un punto de entrada para configurar el aprovisionamiento JIT de conectores SSO dentro de una organización, consulta la [referencia](/organizations/just-in-time-provisioning). ## Preguntas frecuentes \{#faqs} @@ -130,14 +131,14 @@ Logto proporciona un punto de entrada para configurar el aprovisionamiento JIT d - Agregar SSO: Las identidades SSO se vincularán a las cuentas existentes si el correo electrónico coincide. -- Eliminar SSO: Elimina las identidades SSO vinculadas a la cuenta, pero conserva las cuentas de usuario y solicita a los usuarios que configuren métodos alternativos de verificación. +- Eliminar SSO: Elimina las identidades SSO vinculadas a la cuenta, pero conserva las cuentas de usuario y solicita a los usuarios que configuren métodos de verificación alternativos. ## Recursos relacionados \{#related-resources} - SSO iniciado por el IdP y SSO iniciado por el SP + SSO iniciado por el IdP & SSO iniciado por el SP SAML vs. OpenID Connect SAML vs. SSO diff --git a/i18n/es/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/es/docusaurus-plugin-content-docs/current/connectors/social.mdx index 35ec5382c45..2ea2531a99e 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,7 +7,7 @@ sidebar_position: 3 # Conectores sociales -Simplifica la incorporación de usuarios y aumenta las tasas de conversión habilitando el [inicio de sesión social](/end-user-flows/sign-up-and-sign-in/social-sign-in) con Logto. Los usuarios pueden iniciar sesión de manera rápida y segura utilizando sus cuentas de redes sociales existentes, eliminando la necesidad de crear contraseñas o flujos de registro complejos. Logto ofrece una variedad de conectores sociales preconstruidos y admite integraciones personalizadas para una máxima flexibilidad. +Simplifica la incorporación de usuarios y aumenta las tasas de conversión habilitando el [inicio de sesión social](/end-user-flows/sign-up-and-sign-in/social-sign-in) con Logto. Los usuarios pueden iniciar sesión de forma rápida y segura utilizando sus cuentas de redes sociales existentes, eliminando la necesidad de crear contraseñas o flujos de registro complejos. Logto ofrece una variedad de conectores sociales preconstruidos y admite integraciones personalizadas para máxima flexibilidad. ## Elige tus conectores sociales \{#choose-your-social-connectors} @@ -15,7 +15,7 @@ Logto ofrece dos tipos de conectores sociales: ### Conectores sociales populares \{#popular-social-connectors} -Logto proporciona conectores preconfigurados para plataformas sociales populares, listos para su uso inmediato. +Logto proporciona conectores preconfigurados para plataformas sociales populares, listos para usar de inmediato. ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'El conector de Google proporciona una forma concisa para que tu aplicación use el sistema de autenticación OAuth 2.0 de Google.', + description: 'El conector de Google proporciona una forma sencilla para que tu aplicación utilice el sistema de autenticación OAuth 2.0 de Google.', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'El conector de Facebook permite que tu aplicación use el sistema de autenticación OAuth 2.0 de Facebook.', + description: 'El conector de Facebook permite que tu aplicación utilice el sistema de autenticación OAuth 2.0 de Facebook.', customProps: { icon: , } @@ -52,7 +52,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Apple', href: '/integrations/apple', - description: 'El conector oficial de Logto para el inicio de sesión social de Apple.', + description: 'El conector oficial de Logto para el inicio de sesión social con Apple.', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'El conector de Microsoft Azure AD proporciona una forma concisa para que tu aplicación use el sistema de autenticación OAuth 2.0 de Azure.', + description: 'El conector de Microsoft Azure AD proporciona una forma sencilla para que tu aplicación utilice el sistema de autenticación OAuth 2.0 de Azure.', customProps: { icon: , } @@ -70,7 +70,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'GitHub', href: '/integrations/github', - description: 'El conector oficial de Logto para el inicio de sesión social de GitHub.', + description: 'El conector oficial de Logto para el inicio de sesión social con GitHub.', customProps: { icon: , } @@ -79,7 +79,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Discord', href: '/integrations/discord', - description: 'El conector de Discord proporciona una forma para que tu aplicación use Discord como sistema de autorización.', + description: 'El conector de Discord proporciona una forma para que tu aplicación utilice Discord como sistema de autorización.', customProps: { icon: , } @@ -119,27 +119,28 @@ Para requisitos personalizados, utiliza los estándares OAuth 2.0 y OIDC (OpenID /> ``` -Si nuestros conectores estándar no cumplen con tus requisitos específicos, no dudes en [contactarnos](https://logto.productlane.com/roadmap). Para los usuarios de OSS, puedes [implementar tu conector (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) si el requisito es urgente. Siempre damos la bienvenida a [contribuciones](/logto-oss/contribution); tu esfuerzo podría ayudar a otros miembros de la comunidad con las mismas necesidades. +Si nuestros conectores estándar no cumplen con tus requisitos específicos, no dudes en [contactarnos](https://logto.productlane.com/roadmap). Para usuarios de OSS, puedes [implementar tu propio conector (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) si el requisito es urgente. Siempre damos la bienvenida a [contribuciones](/logto-oss/contribution); tu esfuerzo podría ayudar a otros miembros de la comunidad con las mismas necesidades. ## Pasos de configuración \{#configuration-steps} -1. Navega a Consola > Conectores > Conectores sociales. +1. Ve a Consola > Conectores > Conectores sociales. 2. Haz clic en "Agregar conector social" y selecciona el tipo deseado. 3. Sigue la guía README y completa los campos requeridos y personaliza la configuración. -4. Haz clic en "Guardar y Listo" para finalizar. +4. Haz clic en "Guardar y listo" para finalizar. 5. Prueba el conector iniciando un inicio de sesión social. Ten en cuenta las siguientes configuraciones: - **Nombre del proveedor de identidad**: Cada conector social tiene un nombre único de Proveedor de Identidad (IdP) para diferenciar las identidades de los usuarios. Mientras que los conectores comunes usan un nombre de IdP fijo, los conectores personalizados requieren un valor único. Aprende más sobre [nombres de IdP](/connectors/connector-data-structure#target-identity-provider-name) para más detalles. -- **Sincronizar perfiles de usuario**: Elige cuándo sincronizar [la información del perfil de usuario](/user-management/user-data#social-identities) (por ejemplo, avatar, nombre de usuario). El valor predeterminado es "sincronizar solo al registrarse". "sincronizar en cada inicio de sesión" es una alternativa pero puede sobrescribir datos de usuario personalizados. +- **Sincronizar perfiles de usuario**: Elige cuándo sincronizar la [información del perfil de usuario](/user-management/user-data#social-identities) (por ejemplo, avatar, nombre de usuario). El valor predeterminado es "sincronizar solo al registrarse". "sincronizar en cada inicio de sesión" es una alternativa pero puede sobrescribir datos personalizados del usuario. +- **Habilitar almacenamiento de tokens**: Para los conectores sociales compatibles, puedes habilitar el almacenamiento de tokens para guardar de forma segura los tokens de acceso y actualización en el [Secret Vault](/secret-vault) de Logto cuando los usuarios inicien sesión con un proveedor social. Esto permite que tu aplicación acceda a APIs de terceros en nombre del usuario sin requerir que se autentique nuevamente. Aprende más sobre el [almacenamiento federado de tokens](/secret-vault/federated-token-set). -## Habilitar inicio de sesión social \{#enable-social-sign-in} +## Habilita el inicio de sesión social \{#enable-social-sign-in} Una vez que crees un conector social con éxito, puedes habilitarlo como un botón de inicio de sesión social (por ejemplo, Continuar con Google) en la Experiencia de inicio de sesión. -1. Navega a Consola > Experiencia de inicio de sesión > Registro e inicio de sesión. -2. (Opcional) Elige "No aplicable" para el identificador de registro si solo necesitas el inicio de sesión social. +1. Ve a Consola > Experiencia de inicio de sesión > Registro e inicio de sesión. +2. (Opcional) Elige "No aplicable" para el identificador de registro si solo necesitas inicio de sesión social. 3. Agrega los conectores sociales configurados a la sección "Inicio de sesión social". 4. Reordena los conectores según sea necesario. 5. Haz clic en "Guardar cambios" y prueba la "Vista previa en vivo". diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index 5701cb4bf04..4d4c31b71e4 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/facebook sidebar_label: Facebook sidebar_custom_props: - description: Facebook es una plataforma de redes sociales mundial con miles de millones de usuarios. + description: Facebook es una plataforma de redes sociales mundial con miles de millones de usuarios. (Facebook is a worldwide social media platform with billions of users.) tutorial_config_name: Facebook login --- @@ -10,20 +10,67 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configura el inicio de sesión social con Facebook +# Configura el inicio de sesión social con Facebook (Set up social login with Facebook) -El conector oficial de Logto para el inicio de sesión social de Facebook. +Integra el sistema de autenticación OAuth 2.0 de Facebook para habilitar el inicio de sesión con Facebook, vinculación de cuentas y acceso seguro a las API de Facebook. -## Comenzar \{#get-started} +## Comenzar (Get started) \{#get-started} -El conector de Facebook proporciona una forma concisa para que tu aplicación utilice el sistema de autenticación OAuth 2.0 de Facebook. +El conector de Facebook permite la integración con OAuth 2.0 para que tu aplicación pueda: + +- Añadir autenticación de “Iniciar sesión con Facebook” +- Vincular cuentas de usuario con identidades de Facebook +- Sincronizar la información del perfil de usuario desde Facebook +- Acceder a las API de Facebook mediante el almacenamiento seguro de tokens en Logto Secret Vault para tareas de automatización (por ejemplo, responder a hilos; publicar contenido y videos en tu aplicación) + +Para configurar estas funciones de autenticación, primero crea un conector de Facebook en Logto: + +1. Ve a [Logto > Conector > Conector social](https://cloud.logto.io/to/connectors/social). +2. Haz clic en **Agregar conector social**, selecciona **Facebook**, haz clic en **Siguiente** y sigue el tutorial paso a paso para completar la integración. -## Referencias \{#references} +## Utiliza el conector de Facebook (Utilize the Facebook connector) \{#utilize-the-facebook-connector} + +Una vez que hayas creado un conector de Facebook y lo hayas conectado a Facebook, puedes incorporarlo en tus flujos de usuario final. Elige las opciones que se adapten a tus necesidades: + +### Habilita "Iniciar sesión con Facebook" (Enable "Sign-in with Facebook") \{#enable-sign-in-with-facebook} + +1. En Logto Console, ve a Experiencia de inicio de sesión > Registro e inicio de sesión +2. Agrega el conector de Facebook en la sección **Inicio de sesión social** para permitir que los usuarios se autentiquen con Facebook + +Aprende más sobre la [experiencia de inicio de sesión social](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincula o desvincula una cuenta de Facebook (Link or unlink a Facebook account) \{#link-or-unlink-a-facebook-account} + +Utiliza la Account API para construir un Centro de Cuenta personalizado en tu aplicación que permita a los usuarios autenticados vincular o desvincular su cuenta de Facebook. [Sigue el tutorial de Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Se permite habilitar el conector de Facebook solo para vinculación de cuentas y acceso a API, sin habilitarlo para el inicio de sesión social. +::: + +### Accede a la API de Facebook y realiza acciones (Access Facebook API and perform actions) \{#access-facebook-api-and-perform-actions} + +Tu aplicación puede recuperar los tokens de acceso de Facebook almacenados en el Secret Vault para llamar a las API de Facebook y automatizar tareas de backend (por ejemplo, publicar contenido o gestionar publicaciones). Consulta la guía sobre cómo recuperar tokens almacenados para el acceso a API. + +## Gestiona la identidad de Facebook del usuario (Manage user's Facebook identity) \{#manage-user-s-facebook-identity} + +Después de que un usuario vincule su cuenta de Facebook, los administradores pueden gestionar esa conexión en Logto Console: + +1. Navega a Gestión de usuarios y abre el perfil del usuario. +2. En **Conexiones sociales**, localiza el elemento de Facebook y haz clic en **Gestionar**. +3. En esta página, los administradores pueden gestionar la conexión de Facebook del usuario, ver toda la información de perfil otorgada y sincronizada desde su cuenta de Facebook, y comprobar el estado del token de acceso. + +:::note +La respuesta del token de acceso de Facebook no incluye la información específica de los alcances (scope), por lo que Logto no puede mostrar directamente la lista de permisos otorgados por el usuario. Sin embargo, siempre que el usuario haya consentido los alcances solicitados durante la autorización, tu aplicación tendrá los permisos correspondientes al acceder a la API de Facebook. Se recomienda configurar con precisión los alcances requeridos tanto en la Consola de Desarrolladores de Facebook como en Logto para asegurar que tu aplicación tenga el acceso necesario. +::: + +## Referencia (Reference) \{#reference} + +Facebook for Developers - Documentación -- [Facebook Login - Documentation - Facebook for Developers](https://developers.facebook.com/docs/facebook-login/) - - [Manually Build a Login Flow](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [Permissions Guide](https://developers.facebook.com/docs/facebook-login/guides/permissions) + + Documentación de inicio de sesión de Facebook + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index c047d32fe5a..4f311a0a0ac 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,55 +1,100 @@ -### Registra una cuenta de desarrollador de Facebook \{#register-a-facebook-developer-account} +## Paso 1: Configura una aplicación en el Panel de Aplicaciones de Facebook \{#step-1-set-up-an-app-on-facebook-app-dashboard} -[Regístrate como Desarrollador de Facebook](https://developers.facebook.com/docs/development/register/) si aún no tienes una cuenta +Antes de poder usar Facebook como proveedor de autenticación, debes configurar una aplicación en la plataforma de desarrolladores de Facebook para obtener credenciales de OAuth 2.0. -### Configura una aplicación de Facebook \{#set-up-a-facebook-app} +1. [Regístrate como desarrollador de Facebook](https://developers.facebook.com/docs/development/register/) si aún no tienes una cuenta. +2. Visita la página de [Aplicaciones](https://developers.facebook.com/apps). +3. Haz clic en tu aplicación existente o [crea una nueva](https://developers.facebook.com/docs/development/create-an-app) si es necesario. -1. Visita la página de [Apps](https://developers.facebook.com/apps). -2. Haz clic en tu aplicación existente o [crea una nueva](https://developers.facebook.com/docs/development/create-an-app) si es necesario. - - El [tipo de aplicación](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types) seleccionado depende de ti, pero debe tener el producto _Facebook Login_. -3. En la página del panel de la aplicación, desplázate hasta la sección "Agregar un producto" y haz clic en el botón "Configurar" en la tarjeta "Facebook Login". -4. Omite la página de inicio rápido de Facebook Login y haz clic en la barra lateral -> "Productos" -> "Facebook Login" -> "Configuraciones". -5. En la página de Configuraciones de Facebook Login, completa `${your_logto_origin}/callback/${connector_id}` en el campo "Valid OAuth Redirect URIs". El `connector_id` se puede encontrar en la barra superior de la página de detalles del conector en la Consola de Administración de Logto. Por ejemplo: - - `https://logto.dev/callback/${connector_id}` para producción - - `https://localhost:3001/callback/${connector_id}` para pruebas en el entorno local -6. Haz clic en el botón "Guardar cambios" en la esquina inferior derecha. +:::tip +Un caso de uso es la forma principal en que tu aplicación interactuará con Meta y determina qué APIs, funciones, permisos y productos están disponibles para tu aplicación. Si solo necesitas autenticación social (para obtener email y public_profile), selecciona "Authentication and request data from users with Facebook Login". Si deseas acceder a las APIs de Facebook, elige tus casos de uso preferidos; la mayoría también admite la integración de "Facebook Login for business" después de crear la aplicación. +::: -## Componer el JSON del conector \{#compose-the-connector-json} +4. Después de crear la aplicación, en la página del panel de la aplicación, navega a **Casos de uso > Facebook Login > Configuración** o **Facebook Login for business > Configuración**. +5. Rellena el campo **Valid OAuth Redirect URIs** con el **Callback URI** de Logto (cópialo desde tu conector de Facebook en Logto). Después de que los usuarios inicien sesión con Facebook, serán redirigidos aquí con un código de autorización que Logto utiliza para finalizar la autenticación. +6. Navega a **Casos de uso** y haz clic en **Personalizar** de tu caso de uso para añadir los alcances (scopes). Recomendamos añadir `email` y `public_profile`, que son necesarios para implementar el inicio de sesión con Facebook en Logto. -1. En la página del panel de la aplicación de Facebook, haz clic en la barra lateral -> "Configuraciones" -> "Básico". -2. Verás el "App ID" y el "App secret" en el panel. -3. Haz clic en el botón "Mostrar" junto al cuadro de entrada del App secret para copiar su contenido. -4. Completa la configuración del conector de Logto: - - Completa el campo `clientId` con la cadena del _App ID_. - - Completa el campo `clientSecret` con la cadena del _App secret_. - - Completa el campo `scope` con una lista separada por comas o espacios de [permisos](https://developers.facebook.com/docs/permissions/reference) en cadena. Si no especificas un scope, el scope predeterminado es `email,public_profile`. +## Paso 2: Configura el conector de Logto con las credenciales de cliente \{#step-2-set-up-logto-connector-with-client-credentials} -## Probar inicio de sesión con usuarios de prueba de Facebook \{#test-sign-in-with-facebooks-test-users} +1. En el Panel de Aplicaciones de Facebook, haz clic en la barra lateral **Configuración de la aplicación > Básico**. +2. Verás el **App ID** y el **App secret** en el panel. +3. Haz clic en el botón **Mostrar** junto al cuadro de entrada de App secret para revelar y copiar su contenido. +4. Configura los ajustes de tu conector de Facebook en Logto: + - Rellena el campo `clientId` con el **App ID**. + - Rellena el campo `clientSecret` con el **App secret**. + - Haz clic en **Guardar y Listo** en Logto para conectar tu sistema de identidad con Facebook. -Puedes usar las cuentas de los usuarios de prueba, desarrolladores y administradores para probar el inicio de sesión con la aplicación relacionada tanto en [modo de desarrollo](https://developers.facebook.com/docs/development/build-and-test/app-modes) como en modo en vivo. +## Paso 3: Configura los alcances (scopes) \{#step-3-configure-scopes} -También puedes [llevar la aplicación a modo en vivo](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode) directamente para que cualquier usuario de Facebook pueda iniciar sesión con la aplicación. +Los alcances definen los permisos que tu aplicación solicita a los usuarios y controlan a qué datos privados puede acceder tu proyecto desde sus cuentas de Facebook. -- En la página del panel de la aplicación, haz clic en la barra lateral -> "Roles" -> "Usuarios de prueba". -- Haz clic en el botón "Crear usuarios de prueba" para crear un usuario de prueba. -- Haz clic en el botón "Opciones" del usuario de prueba existente, y verás más operaciones, por ejemplo, "Cambiar nombre y contraseña". +### Configura los alcances en el Panel de Aplicaciones de Facebook \{#configure-scopes-in-facebook-app-dashboard} -## Publicar configuraciones de inicio de sesión de Facebook \{#publish-facebook-sign-in-settings} +1. Navega a **Panel de Aplicaciones de Facebook > Casos de uso** y haz clic en el botón **Personalizar**. +2. Añade solo los alcances que tu aplicación necesita. Los usuarios revisarán y autorizarán estos permisos en la pantalla de consentimiento de Facebook: + - **Para autenticación (Requerido)**: `email` y `public_profile`. + - **Para acceso a la API (Opcional)**: Cualquier alcance adicional que tu aplicación necesite (por ejemplo, `threads_content_publish`, `threads_read_replies` para acceder a la API de Threads). Consulta la [Documentación para desarrolladores de Meta](https://developers.facebook.com/docs/) para ver los servicios disponibles. -Por lo general, solo los usuarios de prueba, administradores y desarrolladores pueden iniciar sesión con la aplicación relacionada en [modo de desarrollo](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode). +### Configura los alcances en Logto \{#configure-scopes-in-logto} -Para permitir que los usuarios normales de Facebook inicien sesión con la aplicación en el entorno de producción, es posible que necesites cambiar tu aplicación de Facebook a _[modo en vivo](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_, dependiendo del tipo de aplicación. -Por ejemplo, la aplicación de tipo puramente _empresarial_ no tiene el botón de cambio a "en vivo", pero no bloqueará tu uso. +Elige uno o más de los siguientes enfoques según tus necesidades: -1. En la página del panel de la aplicación de Facebook, haz clic en la barra lateral -> "Configuraciones" -> "Básico". -2. Completa los campos "URL de la política de privacidad" y "Eliminación de datos del usuario" en el panel si es necesario. -3. Haz clic en el botón "Guardar cambios" en la esquina inferior derecha. -4. Haz clic en el botón de cambio a "En vivo" en la barra superior de la aplicación. +**Opción 1: No se necesitan alcances extra de API** -## Tipos de configuración \{#config-types} +- Deja el campo `Scopes` en tu conector de Facebook en Logto en blanco. +- Se solicitará el alcance predeterminado `email public_profile` para asegurar que Logto pueda obtener correctamente la información básica del usuario. -| Nombre | Tipo | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**Opción 2: Solicitar alcances adicionales al iniciar sesión** + +- Ingresa todos los alcances deseados en el campo **Scopes**, separados por espacios. +- Cualquier alcance que incluyas aquí sobrescribe los valores predeterminados, así que asegúrate de incluir siempre los alcances de autenticación: `email public_profile`. + +**Opción 3: Solicitar alcances incrementales más adelante** + +- Después de que el usuario inicie sesión, puedes solicitar alcances adicionales bajo demanda reiniciando un flujo de autorización social federada y actualizando el conjunto de tokens almacenados del usuario. +- Estos alcances adicionales no necesitan ser incluidos en el campo `Scopes` de tu conector de Facebook en Logto, y pueden lograrse a través de la Social Verification API de Logto. + +Siguiendo estos pasos, tu conector de Facebook en Logto solicitará exactamente los permisos que tu aplicación necesita, ni más ni menos. + +:::tip +Si tu aplicación solicita estos alcances para acceder a la API de Facebook y realizar acciones, asegúrate de habilitar **Almacenar tokens para acceso persistente a la API** en el conector de Facebook de Logto. Consulta la siguiente sección para más detalles. +::: + +## Paso 4: Configuración general \{#step-4-general-settings} + +Aquí tienes algunas configuraciones generales que no bloquearán la conexión con Facebook, pero pueden afectar la experiencia de autenticación del usuario final. + +### Sincronizar información de perfil \{#sync-profile-information} + +En el conector de Facebook, puedes establecer la política para sincronizar la información de perfil, como nombres de usuario y avatares. Elige entre: + +- **Sincronizar solo al registrarse**: La información del perfil se obtiene una vez cuando el usuario inicia sesión por primera vez. +- **Sincronizar siempre al iniciar sesión**: La información del perfil se actualiza cada vez que el usuario inicia sesión. + +### Almacenar tokens para acceder a las APIs de Facebook (Opcional) \{#store-tokens-to-access-facebook-apis-optional} + +Si deseas acceder a las APIs de Facebook y realizar acciones con la autorización del usuario (ya sea mediante inicio de sesión social o vinculación de cuentas), Logto necesita obtener alcances específicos de API y almacenar los tokens. + +1. Añade los alcances requeridos siguiendo el tutorial anterior. +2. Habilita **Almacenar tokens para acceso persistente a la API** en el conector de Facebook de Logto. Logto almacenará de forma segura los tokens de acceso de Facebook en el Secret Vault. + +:::note +Facebook no proporciona tokens de actualización (refresh tokens). Sin embargo, cuando el almacenamiento de tokens está habilitado, Logto solicita automáticamente un token de acceso de larga duración (60 días) al autenticar al usuario. Durante este período, los usuarios pueden revocar manualmente los tokens de acceso, pero de lo contrario no necesitarán volver a autorizar para acceder a las APIs de Facebook. Nota: No añadas `offline_access` al campo `Scope`, ya que esto puede causar errores. +::: + +## Paso 5: Prueba el inicio de sesión con usuarios de prueba de Facebook (Opcional) \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +Puedes usar cuentas de usuario de prueba, desarrollador y administrador para probar el inicio de sesión con la aplicación. También puedes publicar la aplicación directamente para que cualquier usuario de Facebook pueda iniciar sesión. + +1. En el Panel de Aplicaciones de Facebook, haz clic en la barra lateral **Roles de la aplicación > Usuarios de prueba**. +2. Haz clic en el botón **Crear usuarios de prueba** para crear un usuario de prueba. +3. Haz clic en el botón **Opciones** de un usuario de prueba existente para ver más operaciones, como "Cambiar nombre y contraseña". + +## Paso 6: Publica la configuración de inicio de sesión con Facebook \{#step-6-publish-facebook-sign-in-settings} + +Normalmente, solo los usuarios de prueba, administradores y desarrolladores pueden iniciar sesión con la aplicación. Para permitir que los usuarios normales de Facebook inicien sesión con la aplicación en el entorno de producción, es posible que debas publicar esta aplicación. + +1. En el Panel de Aplicaciones de Facebook, haz clic en la barra lateral **Publicar**. +2. Rellena los campos **Privacy Policy URL** y **User data deletion** si es necesario. +3. Haz clic en el botón **Guardar cambios** en la esquina inferior derecha. +4. Haz clic en el botón de cambio **Live** en la barra superior de la aplicación. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index 4b1acfa6237..8e391bdfc3a 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -13,26 +13,71 @@ import Integration from './_integration.mdx'; # Configura el inicio de sesión social con GitHub -El conector oficial de Logto para el inicio de sesión social de GitHub. +Integra la aplicación OAuth de GitHub para habilitar el inicio de sesión con GitHub, vinculación de cuentas y acceso seguro a las API de GitHub. ## Comenzar \{#get-started} -El conector de GitHub permite a los usuarios finales iniciar sesión en tu aplicación utilizando sus propias cuentas de GitHub a través del protocolo de autenticación GitHub OAuth 2.0. +El conector de GitHub permite la integración OAuth 2.0 para que tu aplicación pueda: + +- Añadir autenticación "Iniciar sesión con GitHub" +- Vincular cuentas de usuario con identidades de GitHub +- Sincronizar la información del perfil de usuario desde GitHub +- Acceder a las API de GitHub a través del almacenamiento seguro de tokens en Logto Secret Vault para tareas de automatización (por ejemplo, crear incidencias en GitHub, gestionar repositorios desde tu aplicación) + +Para configurar estas funciones de autenticación, primero crea un conector de GitHub en Logto: + +1. Ve a Consola de Logto > Conector > Conector social. +2. Haz clic en **Agregar conector social**, selecciona **GitHub**, haz clic en **Siguiente** y sigue el tutorial paso a paso para completar la integración. -## Probar el conector de GitHub \{#test-github-connector} +## Utiliza el conector de GitHub \{#utilize-the-github-connector} + +Una vez que hayas creado un conector de GitHub y lo hayas conectado a GitHub, puedes incorporarlo en los flujos de usuario final. Elige las opciones que se adapten a tus necesidades: + +### Habilitar "Iniciar sesión con GitHub" \{#enable-sign-in-with-github} + +1. En la Consola de Logto, ve a Experiencia de inicio de sesión > Registro e inicio de sesión. +2. Agrega el conector de GitHub en la sección **Inicio de sesión social** para permitir que los usuarios se autentiquen con GitHub. + +Aprende más sobre la [experiencia de inicio de sesión social](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular o desvincular una cuenta de GitHub \{#link-or-unlink-a-github-account} + +Utiliza la Account API para construir un Centro de Cuenta personalizado en tu aplicación que permita a los usuarios autenticados vincular o desvincular su cuenta de GitHub. [Sigue el tutorial de Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -Eso es todo. El conector de GitHub debería estar disponible ahora. No olvides [habilitar el conector social en la experiencia de inicio de sesión](/connectors/social-connectors/#enable-social-sign-in). +:::tip +Se permite habilitar el conector de GitHub solo para vinculación de cuentas y acceso a API, sin habilitarlo para el inicio de sesión social. +::: + +### Acceder a las API de GitHub y realizar acciones \{#access-github-apis-and-perform-actions} + +Tu aplicación puede recuperar los tokens de acceso de GitHub almacenados en el Secret Vault para llamar a las API de GitHub y automatizar tareas de backend (por ejemplo, crear incidencias, gestionar repositorios o automatizar flujos de trabajo). Consulta la guía sobre cómo recuperar tokens almacenados para el acceso a API. + +## Gestionar la identidad de GitHub del usuario \{#manage-user-s-github-identity} + +Después de que un usuario vincule su cuenta de GitHub, los administradores pueden gestionar esa conexión en la Consola de Logto: + +1. Navega a Consola de Logto > Gestión de usuarios y abre el perfil del usuario. +2. En **Conexiones sociales**, localiza el elemento de GitHub y haz clic en **Gestionar**. +3. En esta página, los administradores pueden gestionar la conexión de GitHub del usuario, ver toda la información de perfil concedida y sincronizada desde su cuenta de GitHub, y comprobar el estado del token de acceso. + +:::note +La respuesta del token de acceso de GitHub no incluye la información específica de los alcances (scopes), por lo que Logto no puede mostrar directamente la lista de permisos concedidos por el usuario. Sin embargo, siempre que el usuario haya consentido los alcances solicitados durante la autorización, tu aplicación tendrá los permisos correspondientes al acceder a la API de GitHub. +::: ## Referencia \{#reference} - GitHub - Developers - Apps + Documentación para desarrolladores de GitHub - Acerca de las aplicaciones - GitHub - Developers - Apps - Creating an OAuth App + Documentación para desarrolladores de GitHub - Crear una aplicación OAuth + + + + Documentación de alcances para aplicaciones OAuth de GitHub diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index b7702625bd3..e1a66bffdd1 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,35 +1,99 @@ -### Iniciar sesión con cuenta de GitHub \{#sign-in-with-github-account} +## Paso 1: Crea una aplicación OAuth en GitHub \{#step-1-create-an-oauth-app-on-github} -Ve al [sitio web de GitHub](https://github.com/) e inicia sesión con tu cuenta de GitHub. Puedes registrar una nueva cuenta si no tienes una. +Antes de poder usar GitHub como proveedor de autenticación, debes crear una aplicación OAuth en GitHub para obtener credenciales de OAuth 2.0. -### Crear y configurar la aplicación OAuth \{#create-and-configure-oauth-app} +1. Ve a [GitHub](https://github.com/) e inicia sesión con tu cuenta, o crea una nueva si es necesario. +2. Navega a [Settings > Developer settings > OAuth apps](https://github.com/settings/developers). +3. Haz clic en **New OAuth App** para registrar una nueva aplicación: + - **Application name**: Ingresa un nombre descriptivo para tu aplicación. + - **Homepage URL**: Ingresa la URL de la página principal de tu aplicación. + - **Authorization callback URL**: Copia el **Callback URI** de tu conector de GitHub en Logto y pégalo aquí. Después de que los usuarios inicien sesión con GitHub, serán redirigidos aquí con un código de autorización que Logto utiliza para completar la autenticación. + - **Application description**: (Opcional) Agrega una breve descripción de tu aplicación. +4. Haz clic en **Register application** para crear la aplicación OAuth. -Sigue la guía de [creación de una aplicación OAuth](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) y registra una nueva aplicación. +:::note +Sugerimos no marcar la casilla **Enable Device Flow**, ya que los usuarios que inicien sesión con GitHub en dispositivos móviles tendrían que confirmar la acción inicial de inicio de sesión en la aplicación móvil de GitHub. Muchos usuarios de GitHub no instalan la aplicación móvil de GitHub en sus teléfonos, lo que podría bloquear el flujo de inicio de sesión. Solo habilita esto si esperas que los usuarios finales confirmen su flujo de inicio de sesión a través de la aplicación móvil de GitHub. Consulta los detalles sobre el [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). -Nombra tu nueva aplicación OAuth en **Nombre de la aplicación** y completa la **URL de la página de inicio** de la aplicación. Puedes dejar el campo **Descripción de la aplicación** en blanco y personalizar la **URL de devolución de llamada de autorización** como `${your_logto_origin}/callback/${connector_id}`. El `connector_id` se puede encontrar en la barra superior de la página de detalles del conector en la Consola de Administración de Logto. +Para más detalles sobre cómo configurar aplicaciones OAuth en GitHub, consulta [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). +::: -:::note +## Paso 2: Configura tu conector de Logto \{#step-2-configure-your-logto-connector} + +Después de crear la aplicación OAuth en GitHub, serás redirigido a una página de detalles donde podrás copiar el Client ID y generar un Client secret. + +1. Copia el **Client ID** de tu aplicación OAuth de GitHub y pégalo en el campo `clientId` en Logto. +2. Haz clic en **Generate a new client secret** en GitHub para crear un nuevo secreto, luego cópialo y pégalo en el campo `clientSecret` en Logto. +3. Haz clic en **Save and Done** en Logto para conectar tu sistema de identidad con GitHub. + +:::warning +Mantén tu Client secret seguro y nunca lo expongas en código del lado del cliente. Los client secrets de GitHub no se pueden recuperar si se pierden; tendrás que generar uno nuevo. +::: + +## Paso 3: Configura los alcances (Scopes) (Opcional) \{#step-3-configure-scopes-optional} + +Los alcances (Scopes) definen los permisos que tu aplicación solicita a los usuarios y controlan a qué datos puede acceder tu aplicación desde sus cuentas de GitHub. + +Utiliza el campo `Scopes` en Logto para solicitar permisos adicionales a GitHub. Elige uno de los siguientes enfoques según tus necesidades: + +### Opción 1: No se necesitan alcances de API adicionales \{#option-1-no-extra-api-scopes-needed} + +- Deja el campo `Scopes` en tu conector de GitHub en Logto en blanco. +- Se solicitará el alcance predeterminado `read:user` para asegurar que Logto pueda obtener correctamente la información básica del usuario (por ejemplo, correo electrónico, nombre, avatar). -Si encuentras el mensaje de error "La redirect_uri DEBE coincidir con la URL de devolución de llamada registrada para esta aplicación." al iniciar sesión, intenta alinear la URL de devolución de llamada de autorización de tu aplicación OAuth de GitHub y la URL de redirección de tu aplicación Logto (por supuesto, incluyendo el protocolo) para resolver el problema. +### Opción 2: Solicitar alcances adicionales al iniciar sesión \{#option-2-request-additional-scopes-at-sign-in} +- Consulta todos los [alcances de GitHub para aplicaciones OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) disponibles y agrega solo los que tu aplicación necesite. +- Ingresa todos los alcances deseados en el campo **Scopes**, separados por espacios. +- Cualquier alcance que listes aquí sobrescribe los valores predeterminados, así que siempre incluye el alcance de autenticación: `read:user`. +- Alcances adicionales comunes incluyen: + - `repo`: Control total de repositorios privados + - `public_repo`: Acceso a repositorios públicos + - `user:email`: Acceso a direcciones de correo electrónico del usuario + - `notifications`: Acceso a notificaciones +- Asegúrate de que todos los alcances estén escritos correctamente y sean válidos. Un alcance incorrecto o no soportado resultará en un error de "Invalid scope" por parte de GitHub. + +### Opción 3: Solicitar alcances incrementales más adelante \{#option-3-request-incremental-scopes-later} + +- Después de que el usuario inicie sesión, puedes solicitar alcances adicionales bajo demanda reiniciando un flujo de autorización social federado y actualizando el conjunto de tokens almacenados del usuario. +- Estos alcances adicionales no necesitan ser ingresados en el campo `Scopes` de tu conector de GitHub en Logto, y pueden lograrse a través de la Social Verification API de Logto. + +Siguiendo estos pasos, tu conector de GitHub en Logto solicitará exactamente los permisos que tu aplicación necesita, ni más ni menos. + +:::tip +Si tu aplicación solicita estos alcances para acceder a la API de GitHub y realizar acciones, asegúrate de habilitar **Store tokens for persistent API access** en el conector de GitHub de Logto. Consulta la siguiente sección para más detalles. ::: -Sugerimos no marcar la casilla antes de **Habilitar flujo de dispositivo**, o los usuarios que inicien sesión con GitHub en dispositivos móviles deberán confirmar la acción de inicio de sesión inicial en la aplicación de GitHub. Muchos usuarios de GitHub no instalan la aplicación móvil de GitHub en sus teléfonos, lo que podría bloquear el flujo de inicio de sesión. Por favor, ignora nuestra sugerencia si esperas que los usuarios finales confirmen su flujo de inicio de sesión. Consulta los detalles del [flujo de dispositivo](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). +## Paso 4: Configuración general \{#step-4-general-settings} + +Aquí tienes algunas configuraciones generales que no bloquearán la conexión con GitHub pero pueden afectar la experiencia de autenticación del usuario final. + +### Sincronizar información del perfil \{#sync-profile-information} -### Gestión de aplicaciones OAuth \{#managing-oauth-apps} +En el conector de GitHub, puedes establecer la política para sincronizar la información del perfil, como nombres de usuario y avatares. Elige entre: -Ve a la [página de aplicaciones OAuth](https://github.com/settings/developers) y puedes agregar, editar o eliminar aplicaciones OAuth existentes. También puedes encontrar el `Client ID` y generar `Client secrets` en las páginas de detalles de la aplicación OAuth. +- **Solo sincronizar al registrarse**: La información del perfil se obtiene una vez cuando el usuario inicia sesión por primera vez. +- **Siempre sincronizar al iniciar sesión**: La información del perfil se actualiza cada vez que el usuario inicia sesión. -### Configura tu conector \{#configure-your-connector} +### Almacenar tokens para acceder a las APIs de GitHub (Opcional) \{#store-tokens-to-access-github-apis-optional} + +Si deseas acceder a las APIs de GitHub y realizar acciones con la autorización del usuario (ya sea mediante inicio de sesión social o vinculación de cuentas), Logto necesita obtener alcances de API específicos y almacenar los tokens. + +1. Agrega los alcances requeridos siguiendo las instrucciones anteriores. +2. Habilita **Store tokens for persistent API access** en el conector de GitHub de Logto. Logto almacenará de forma segura los tokens de acceso de GitHub en el Secret Vault. + +:::note +Cuando usas una **OAuth App** de GitHub como se describe en este tutorial, no puedes obtener un refresh token de GitHub porque su token de acceso no expira a menos que el usuario lo revoque manualmente. Por lo tanto, no necesitas agregar `offline_access` en el campo `Scopes`; hacerlo puede causar un error. + +Si deseas que el token de acceso expire o usar refresh tokens, considera integrar con una **GitHub App** en su lugar. Aprende sobre las [diferencias entre GitHub Apps y OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). +::: -Completa el campo `clientId` y `clientSecret` con el _Client ID_ y _Client Secret_ que obtuviste de las páginas de detalles de la aplicación OAuth mencionadas en la sección anterior. +## Paso 5: Prueba tu integración (Opcional) \{#step-5-test-your-integration-optional} -`scope` es una lista delimitada por espacios de [alcances (scopes)](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). Si no se proporciona, el alcance por defecto será `read:user`. +Antes de lanzar, prueba tu integración con GitHub: -### Tipos de configuración \{#config-types} +1. Usa el conector en un tenant de desarrollo de Logto. +2. Verifica que los usuarios puedan iniciar sesión con GitHub. +3. Comprueba que se soliciten los alcances correctos. +4. Prueba las llamadas a la API si estás almacenando tokens. -| Nombre | Tipo | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +Las aplicaciones OAuth de GitHub funcionan con cualquier cuenta de usuario de GitHub de inmediato; no es necesario tener usuarios de prueba ni aprobación de la aplicación como en otras plataformas. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index 707269055a9..917b0de9100 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: - description: Google es un proveedor principal de tecnología de motores de búsqueda y servicio de correo electrónico. + description: Google es un proveedor principal de tecnología de motores de búsqueda y servicios de correo electrónico. tutorial_config_name: Google OAuth app --- @@ -12,14 +12,66 @@ import Integration from './_integration.mdx'; # Configura el inicio de sesión social con Google -El conector de Google proporciona una manera concisa para que tu aplicación utilice el sistema de autenticación OAuth 2.0 de Google. +Integra el sistema de autenticación OAuth 2.0 de Google para habilitar el inicio de sesión con Google, vinculación de cuentas y acceso seguro a las APIs de Google. +## Comenzar \{#get-started} + +El conector de Google permite la integración con OAuth 2.0 para que tu aplicación pueda: + +- Añadir autenticación de "Iniciar sesión con Google" +- Vincular cuentas de usuario con identidades de Google +- Sincronizar la información del perfil de usuario desde Google +- Acceder a las APIs de Google mediante el almacenamiento seguro de tokens en Logto Secret Vault para tareas de automatización (por ejemplo, editar Google Docs, gestionar eventos de Calendar en tu app) + +Para configurar estas funciones de autenticación, primero crea un conector de Google en Logto: + +1. Ve a Consola de Logto > Conector > Conector social. +2. Haz clic en **Agregar conector social**, selecciona **Google**, haz clic en **Siguiente** y sigue el tutorial paso a paso para completar la integración. + -## Referencias \{#references} +## Utiliza el conector de Google \{#utilize-the-google-connector} + +Una vez que hayas creado un conector de Google y lo hayas conectado con Google, puedes incorporarlo en los flujos de tus usuarios finales. Elige las opciones que se adapten a tus necesidades: + +### Habilita "Iniciar sesión con Google" \{#enable-sign-in-with-google} + +1. En la Consola de Logto, ve a Experiencia de inicio de sesión > Registro e inicio de sesión. +2. Agrega el conector de Google en la sección **Inicio de sesión social** para permitir que los usuarios se autentiquen con Google. +3. Opcionalmente, habilita **Google One Tap** en las páginas de inicio de sesión y registro para una experiencia de autenticación más fluida. + +Aprende más sobre la [experiencia de inicio de sesión social](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincula o desvincula una cuenta de Google \{#link-or-unlink-a-google-account} + +Utiliza el Account API para construir un Centro de Cuenta personalizado en tu aplicación que permita a los usuarios autenticados vincular o desvincular su cuenta de Google. [Sigue el tutorial de Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Está permitido habilitar el conector de Google solo para vinculación de cuentas y acceso a API, sin habilitarlo para el inicio de sesión social. +::: + +### Accede a las APIs de Google y realiza acciones \{#access-google-apis-and-perform-actions} + +Tu aplicación puede recuperar los tokens de acceso de Google almacenados en el Secret Vault para llamar a las APIs de Google y automatizar tareas de backend (por ejemplo, gestionar archivos de Google Drive, crear eventos en Calendar o enviar correos electrónicos a través de Gmail). Consulta la guía sobre cómo recuperar tokens almacenados para el acceso a API. + +## Gestiona la identidad de Google del usuario \{#manage-user-s-google-identity} + +Después de que un usuario vincule su cuenta de Google, los administradores pueden gestionar esa conexión en la Consola de Logto: + +1. Navega a Consola de Logto > Gestión de usuarios y abre el perfil del usuario. +2. En **Conexiones sociales**, localiza el elemento de Google y haz clic en **Gestionar**. +3. En esta página, los administradores pueden gestionar la conexión de Google del usuario, ver toda la información de perfil otorgada y sincronizada desde su cuenta de Google, y comprobar el estado del token de acceso. + +## Referencia \{#reference} - Google Identity: Setting up OAuth 2.0 + Google Identity: Configuración de OAuth 2.0 + + + Google Identity Services (One Tap) + + +Google Cloud Console diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index fd83deffb53..cfa17c8df25 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## Configura un proyecto en la Google API Console \{#set-up-a-project-in-the-google-api-console} +## Paso 1: Crea un proyecto en Google Auth Platform \{#step-1-create-a-project-on-google-auth-platform} + +Antes de poder usar Google como proveedor de autenticación, debes configurar un proyecto en Google Cloud Console para obtener credenciales de OAuth 2.0. Si ya tienes un proyecto, puedes omitir este paso. + +1. Visita la [Google Cloud Console](https://console.cloud.google.com/) e inicia sesión con tu cuenta de Google. +2. Haz clic en el botón **Seleccionar un proyecto** en la barra superior del menú y luego haz clic en el botón **Nuevo proyecto** para crear un proyecto. +3. En tu proyecto recién creado, navega a **APIs y servicios > Pantalla de consentimiento OAuth** para configurar tu aplicación: + - **Información de la aplicación**: Ingresa el **Nombre de la aplicación** y el **Correo electrónico de soporte** que se mostrarán en la página de consentimiento. + - **Audiencia (Audience)**: Selecciona tu tipo de audiencia preferido: + - **Interna (Internal)** - Solo para usuarios de Google Workspace dentro de tu organización. + - **Externa (External)** - Para cualquier usuario de Google (requiere verificación para uso en producción). + - **Información de contacto**: Proporciona direcciones de correo electrónico para que Google pueda notificarte sobre cualquier cambio en tu proyecto. + - Marca **Acepto las políticas de Google** para finalizar la configuración básica. +4. Opcionalmente, ve a la sección **Branding** para editar la información del producto y subir el **Logo de tu aplicación**, que aparecerá en la pantalla de consentimiento OAuth para ayudar a los usuarios a reconocer tu app. + +:::tip +Si eliges el tipo de audiencia **Externa (External)**, deberás agregar usuarios de prueba durante el desarrollo y publicar tu aplicación para su uso en producción. +::: + +## Paso 2: Crea credenciales OAuth 2.0 \{#step-2-create-oauth-2-0-credentials} + +Navega a la página de [Credenciales](https://console.cloud.google.com/apis/credentials) en Google Cloud Console y crea credenciales OAuth para tu aplicación. + +1. Haz clic en **Crear credenciales > ID de cliente de OAuth**. +2. Selecciona **Aplicación web (Web application)** como tipo de aplicación. +3. Completa el **Nombre** de tu cliente OAuth. Esto te ayuda a identificar las credenciales y no se muestra a los usuarios finales. +4. Configura los URI autorizados: + - **Orígenes JavaScript autorizados**: Agrega el origen de tu instancia Logto (por ejemplo, `https://tu-dominio-logto.com`) + - **URI de redirección autorizados**: Agrega el **Callback URI** de Logto (cópialo desde tu conector de Google en Logto) +5. Haz clic en **Crear** para generar el cliente OAuth. + +## Paso 3: Configura el conector de Logto con las credenciales \{#step-3-configure-logto-connector-with-credentials} + +Después de crear el cliente OAuth, Google mostrará una ventana modal con tus credenciales: + +1. Copia el **ID de cliente (Client ID)** y pégalo en el campo `clientId` en Logto. +2. Copia el **Secreto de cliente (Client secret)** y pégalo en el campo `clientSecret` en Logto. +3. Haz clic en **Guardar y Listo** en Logto para conectar tu sistema de identidad con Google. + +:::warning +Mantén tu secreto de cliente seguro y nunca lo expongas en código del lado del cliente. Si se ve comprometido, genera uno nuevo de inmediato. +::: + +## Paso 4: Configura los alcances (Scopes) \{#step-4-configure-scopes} + +Los alcances (Alcances (Scopes)) definen los permisos que tu aplicación solicita a los usuarios y controlan a qué datos puede acceder tu app desde sus cuentas de Google. + +### Configura los alcances en Google Cloud Console \{#configure-scopes-in-google-cloud-console} + +1. Navega a **APIs y servicios > Pantalla de consentimiento OAuth > Alcances (Scopes)**. +2. Haz clic en **Agregar o quitar alcances (Add or Remove Scopes)** y selecciona solo los alcances que tu aplicación requiere: + - **Autenticación (Authentication) (Obligatorio)**: + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **Acceso a API (Opcional)**: Agrega cualquier alcance adicional necesario para tu app (por ejemplo, Drive, Calendar, YouTube). Explora la [Biblioteca de API de Google](https://console.cloud.google.com/apis/library) para encontrar servicios disponibles. Si tu app necesita acceso a APIs de Google más allá de los permisos básicos, primero habilita las APIs específicas que tu app usará (por ejemplo, Google Drive API, Gmail API, Calendar API) en la Biblioteca de API de Google. +3. Haz clic en **Actualizar (Update)** para confirmar la selección. +4. Haz clic en **Guardar y continuar (Save and Continue)** para aplicar los cambios. -- Visita la [Google API Console](https://console.developers.google.com) e inicia sesión con tu cuenta de Google. -- Haz clic en el botón **Select a project** en la barra de menú superior y haz clic en el botón **New Project** para crear un proyecto. -- En tu proyecto recién creado, haz clic en **APIs & Services** para entrar al menú de **APIs & Services**. +### Configura los alcances en Logto \{#configure-scopes-in-logto} -## Configura tu pantalla de consentimiento \{#configure-your-consent-screen} +Elige una o más de las siguientes opciones según tus necesidades: -### Configura y registra tu aplicación \{#configure-and-register-your-application} +**Opción 1: No se necesitan alcances de API adicionales** -- En el menú de la izquierda **APIs & Services**, haz clic en el botón **OAuth consent screen**. -- Elige el **User Type** que desees y haz clic en el botón **Create**. (Nota: Si seleccionas **External** como tu **User Type**, necesitarás agregar usuarios de prueba más tarde). +- Deja el campo `Scopes` en tu conector de Google en Logto en blanco. +- Los alcances predeterminados `openid profile email` serán solicitados para asegurar que Logto pueda obtener correctamente la información básica del usuario. -Ahora estarás en la página **Edit app registration**. +**Opción 2: Solicitar alcances adicionales al iniciar sesión** -### Editar el registro de la aplicación \{#edit-app-registration} +- Ingresa todos los alcances deseados en el campo **Scopes**, separados por espacios. +- Cualquier alcance que listes aquí sobrescribe los predeterminados, así que siempre incluye los alcances de autenticación: `https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`. +- Usa URLs completas de los alcances. Ejemplo: `https://www.googleapis.com/auth/calendar.readonly`. -#### Configurar la pantalla de consentimiento de OAuth \{#config-oauth-consent-screen} +**Opción 3: Solicitar alcances incrementales más adelante** -- Sigue las instrucciones para completar el formulario de la **OAuth consent screen**. -- Haz clic en **SAVE AND CONTINUE** para continuar. +- Después de que el usuario inicie sesión, puedes solicitar alcances adicionales bajo demanda reiniciando un flujo de autorización social federada y actualizando el conjunto de tokens almacenados del usuario. +- Estos alcances adicionales no necesitan ser rellenados en el campo `Scopes` de tu conector de Google en Logto, y se pueden lograr a través de la API de Verificación Social de Logto. -#### Configurar alcances \{#config-scopes} +Siguiendo estos pasos, tu conector de Google en Logto solicitará exactamente los permisos que tu app necesita, ni más ni menos. -- Haz clic en **ADD OR REMOVE SCOPES** y selecciona `../auth/userinfo.email`, `../auth/userinfo.profile` y `openid` en el cajón emergente, y haz clic en **UPDATE** para finalizar. Se recomienda que consideres agregar todos los alcances que puedas usar, de lo contrario, algunos alcances que agregaste en la configuración pueden no funcionar. -- Completa el formulario según lo necesites. -- Haz clic en **SAVE AND CONTINUE** para continuar. +:::tip +Si tu app solicita estos alcances para acceder a la API de Google y realizar acciones, asegúrate de habilitar **Almacenar tokens para acceso persistente a la API** en el conector de Google en Logto. Consulta la siguiente sección para más detalles. +::: -#### Agregar usuarios de prueba (solo tipo de usuario externo) \{#add-test-users-external-user-type-only} +## Paso 5: Personaliza los prompts de autenticación \{#step-5-customize-authentication-prompts} -- Haz clic en **ADD USERS** y agrega usuarios de prueba para permitir que estos usuarios accedan a tu aplicación mientras la pruebas. -- Haz clic en **SAVE AND CONTINUE** para continuar. +Configura **Prompts** en Logto para controlar la experiencia de autenticación del usuario. Prompts es un arreglo de cadenas que especifica el tipo de interacción de usuario requerida: -Ahora deberías tener configurada la pantalla de consentimiento de Google OAuth 2.0. +- `none` - El servidor de autorización no muestra ninguna pantalla de autenticación ni de consentimiento. Devuelve un error si el usuario no está ya autenticado y no ha preconfigurado el consentimiento para los alcances solicitados. Úsalo para comprobar la autenticación y/o consentimiento existentes. +- `consent` - El servidor de autorización solicita el consentimiento del usuario antes de devolver información al cliente. Es necesario para habilitar el **acceso sin conexión (offline access)** para el acceso a la API de Google. +- `select_account` - El servidor de autorización solicita al usuario seleccionar una cuenta. Esto permite a los usuarios con varias cuentas de Google elegir cuál usar para la autenticación. -## Obtener credenciales de OAuth 2.0 \{#obtain-oauth-20-credentials} +## Paso 6: Configuración general \{#step-6-general-settings} -- En el menú de la izquierda **APIs & Services**, haz clic en el botón **Credentials**. -- En la página **Credentials**, haz clic en el botón **+ CREATE CREDENTIALS** en la barra de menú superior y selecciona **OAuth client ID**. -- En la página **Create OAuth client ID**, selecciona **Web application** como el tipo de aplicación. -- Completa la información básica de tu aplicación. -- Haz clic en **+ Add URI** para agregar un dominio autorizado a la sección **Authorized JavaScript origins**. Este es el dominio desde el cual se servirá tu página de autorización de Logto. En nuestro caso, será `${your_logto_origin}`. por ejemplo, `https://logto.dev`. -- Haz clic en **+ Add URI** en la sección **Authorized redirect URIs** para configurar las **Authorized redirect URIs**, que redirigen al usuario a la aplicación después de iniciar sesión. En nuestro caso, será `${your_logto_endpoint}/callback/${connector_id}`. por ejemplo, `https://logto.dev/callback/${connector_id}`. El `connector_id` se puede encontrar en la barra superior de la página de detalles del conector en el Logto Admin Console. -- Haz clic en **Create** para finalizar y luego obtendrás el **Client ID** y el **Client Secret**. +Aquí tienes algunas configuraciones generales que no bloquearán la conexión con Google pero pueden afectar la experiencia de autenticación del usuario final. -## Configura tu conector \{#configure-your-connector} +### Sincronizar información de perfil \{#sync-profile-information} -Completa el campo `clientId` y `clientSecret` con el _Client ID_ y _Client Secret_ que obtuviste de las páginas de detalles de la aplicación OAuth mencionadas en la sección anterior. +En el conector de Google, puedes establecer la política para sincronizar la información de perfil, como nombres de usuario y avatares. Elige entre: -`scope` es una lista delimitada por espacios de [alcances](https://developers.google.com/identity/protocols/oauth2/scopes). Si no se proporciona, el alcance por defecto será `openid profile email`. +- **Sincronizar solo al registrarse**: La información del perfil se obtiene una vez cuando el usuario inicia sesión por primera vez. +- **Sincronizar siempre al iniciar sesión**: La información del perfil se actualiza cada vez que el usuario inicia sesión. -`prompts` es un arreglo de cadenas que especifica el tipo de interacción del usuario que se requiere. La cadena puede ser uno de los siguientes valores: +### Almacenar tokens para acceder a las APIs de Google (Opcional) \{#store-tokens-to-access-google-apis-optional} -- `none`: El servidor de autorización no muestra ninguna pantalla de autenticación o consentimiento del usuario; devolverá un error si el usuario no está ya autenticado y no ha preconfigurado el consentimiento para los alcances solicitados. Puedes usar none para verificar la autenticación y/o consentimiento existentes. -- `consent`: El servidor de autorización solicita el consentimiento del usuario antes de devolver información al cliente. -- `select_account`: El servidor de autorización solicita al usuario que seleccione una cuenta de usuario. Esto permite a un usuario que tiene múltiples cuentas en el servidor de autorización seleccionar entre las múltiples cuentas para las que puede tener sesiones actuales. +Si deseas acceder a [APIs de Google](https://console.cloud.google.com/apis/library) y realizar acciones con la autorización del usuario (ya sea mediante inicio de sesión social o vinculación de cuentas), Logto necesita obtener alcances específicos de API y almacenar tokens. -### Tipos de configuración \{#config-types} +1. Agrega los alcances requeridos en la configuración de la pantalla de consentimiento OAuth de Google Cloud Console y en el conector de Google en Logto. +2. Habilita **Almacenar tokens para acceso persistente a la API** en el conector de Google en Logto. Logto almacenará de forma segura los tokens de acceso y actualización de Google en el Secret Vault. +3. Para asegurar que se devuelvan tokens de actualización, configura tu conector de Google en Logto de la siguiente manera: + - Establece **Prompts** para incluir `consent` + - Habilita **Acceso sin conexión (Offline Access)** -| Nombre | Tipo | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +No necesitas agregar `offline_access` en el campo `Scope` de Logto; hacerlo puede causar un error. Google utiliza `access_type=offline` automáticamente cuando el acceso sin conexión está habilitado. +::: -## Habilitar Google One Tap \{#enable-google-one-tap} +## Paso 7: Habilita Google One Tap (Opcional) \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) es una forma segura y fácil de permitir que los usuarios inicien sesión en tu sitio web o aplicación con su cuenta de Google. +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) es una forma segura y simplificada de permitir que los usuarios inicien sesión en tu sitio web con su cuenta de Google usando una interfaz emergente. -Una vez que tengas configurado el conector de Google, verás una tarjeta para Google One Tap en la página de detalles del conector. Puedes habilitar Google One Tap en tus páginas de registro e inicio de sesión activando el interruptor. +Una vez que tengas configurado el conector de Google, verás una tarjeta para Google One Tap en la página de detalles del conector. Habilita Google One Tap activando el interruptor. -Cuando habilitas Google One Tap, puedes configurar las siguientes opciones: +### Opciones de configuración de Google One Tap \{#google-one-tap-configuration-options} -- **Auto-select credential if possible**: Inicia sesión automáticamente al usuario con la cuenta de Google si se cumplen [ciertas condiciones](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out). -- **Cancel the prompt if user click/tap outside**: Cierra el aviso de Google One Tap si el usuario hace clic o toca fuera del aviso. Si está deshabilitado, el usuario debe hacer clic en el botón de cerrar para descartar el aviso. -- **Enable Upgraded One Tap UX on ITP browsers**: Habilita la experiencia de usuario mejorada de Google One Tap en navegadores con Intelligent Tracking Prevention (ITP). Por favor, consulta [esta página](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) para más información. +- **Seleccionar automáticamente la credencial si es posible**: Inicia sesión automáticamente al usuario con la cuenta de Google si se cumplen [ciertas condiciones](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out). +- **Cancelar el prompt si el usuario hace clic/toca fuera**: Cierra el prompt de Google One Tap si el usuario hace clic o toca fuera del prompt. Si está deshabilitado, el usuario debe hacer clic en el botón de cerrar para descartar el prompt. +- **Habilitar la experiencia mejorada de One Tap en navegadores ITP**: Habilita la experiencia de usuario mejorada de Google One Tap en navegadores con Intelligent Tracking Prevention (ITP). Consulta [esta documentación](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) para más información. -:::caution -Asegúrate de agregar el origen de tu servidor a la sección **Authorized JavaScript origins** en la configuración de la pantalla de consentimiento de OAuth. De lo contrario, Google One Tap no se podrá mostrar. +:::warning +Asegúrate de agregar tu dominio en la sección **Orígenes JavaScript autorizados** en la configuración de tu cliente OAuth. De lo contrario, Google One Tap no podrá mostrarse. ::: +### Limitaciones importantes con Google One Tap \{#important-limitations-with-google-one-tap} + +Si habilitas **Almacenar tokens para acceso persistente a la API** junto con **Google One Tap**, no recibirás automáticamente un token de acceso ni los alcances solicitados. + +El inicio de sesión con Google One Tap (a diferencia del botón estándar "Iniciar sesión con Google") **no** emite un token de acceso OAuth. Solo devuelve un token de ID (un JWT firmado) que verifica la identidad del usuario, pero no otorga acceso a la API. + +Para acceder a las APIs de Google con usuarios de Google One Tap, puedes usar la API de Verificación Social de Logto para reiniciar un flujo de autorización social federada después de que el usuario inicie sesión con Google One Tap. Esto te permite solicitar alcances adicionales según sea necesario y actualizar el conjunto de tokens almacenados del usuario, sin requerir que los alcances se prellen en el conector de Google en Logto. Este enfoque permite una autorización incremental, por lo que los usuarios solo reciben solicitudes de permisos adicionales cuando tu app realmente los necesita. + +Obtén más información sobre las [limitaciones de Google One Tap](https://developers.google.com/identity/gsi/web/guides/overview) en la documentación oficial. + +## Paso 8: Prueba y publica tu aplicación \{#step-8-test-and-publish-your-app} + +### Para aplicaciones internas \{#for-internal-apps} + +Si tu tipo de **Audiencia (Audience)** en Google está configurado como **Interna (Internal)**, tu aplicación solo estará disponible para usuarios de Google Workspace dentro de tu organización. Puedes probar usando cualquier cuenta de tu organización. + +### Para aplicaciones externas \{#for-external-apps} + +Si tu tipo de **Audiencia (Audience)** es **Externa (External)**: + +1. **Durante el desarrollo**: Navega a **Pantalla de consentimiento OAuth > Usuarios de prueba (Test users)** y agrega las direcciones de correo electrónico de los usuarios de prueba. Solo estos usuarios podrán iniciar sesión con tu app. +2. **Para producción**: Haz clic en **Publicar aplicación (Publish App)** en la sección de pantalla de consentimiento OAuth para que esté disponible para cualquier persona con una cuenta de Google. + :::note -Para habilitar Google One Tap en tu sitio web (más allá de la experiencia de inicio de sesión de Logto), esta función está en desarrollo. Por favor, mantente atento a las actualizaciones. +Las aplicaciones con alcances sensibles o restringidos pueden requerir la verificación de Google antes de poder publicarse. Este proceso puede tardar varias semanas. ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index 01bd9f75636..913fd73b35f 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -2,17 +2,17 @@ slug: /integrations/oauth2 sidebar_label: OAuth 2.0 (Social) sidebar_custom_props: - description: El marco de autorización OAuth 2.0 permite que una aplicación de terceros obtenga acceso limitado a un servicio HTTP. + description: El marco de autorización OAuth 2.0 permite que una aplicación de terceros obtenga acceso limitado a un servicio HTTP. (The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service.) logoFilename: 'oauth.svg' tutorial_name: OAuth2 -tutorial_config_name: Aplicación estándar OAuth 2.0 +tutorial_config_name: Standard OAuth 2.0 app --- import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configura el inicio de sesión social con el protocolo OAuth 2.0 +# Configura el inicio de sesión social con el protocolo OAuth 2.0 (Set up social login with OAuth 2.0 protocol) El conector oficial de Logto para el protocolo OAuth 2.0. @@ -20,11 +20,21 @@ El conector oficial de Logto para el protocolo OAuth 2.0. ## Comenzar \{#get-started} -El conector OAuth permite la conexión de Logto a un proveedor de identidad social arbitrario que admite el protocolo OAuth 2.0. +El conector OAuth permite la conexión de Logto con cualquier proveedor de identidad social que admita el protocolo OAuth 2.0. Utiliza el conector OAuth para que tu aplicación pueda: + +- Añadir botones de inicio de sesión social +- Vincular cuentas de usuario con identidades sociales +- Sincronizar la información del perfil del usuario desde el proveedor social +- Acceder a APIs de terceros mediante el almacenamiento seguro de tokens en Logto Secret Vault para tareas de automatización (por ejemplo, editar Google Docs, gestionar eventos de Calendar en tu aplicación) + +Para configurar estas funciones de autenticación, primero crea un conector OAuth 2.0 en Logto: + +1. Ve a Consola de Logto > Conector > Conector social. +2. Haz clic en **Agregar conector social**, selecciona **OAuth 2.0**, haz clic en **Siguiente** y sigue el tutorial paso a paso para completar la integración. :::note -El conector OAuth es un tipo especial de conector en Logto, puedes agregar algunos conectores basados en el protocolo OAuth. +El conector OAuth es un tipo especial de conector en Logto; puedes agregar múltiples conectores basados en el protocolo OAuth. ::: @@ -32,4 +42,6 @@ El conector OAuth es un tipo especial de conector en Logto, puedes agregar algun ## Referencia \{#reference} -El marco de autorización OAuth 2.0 + + El marco de autorización OAuth 2.0 (The OAuth 2.0 Authorization Framework) + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index ce19d85fc63..5467e35a07f 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ ## Crea tu aplicación OAuth \{#create-your-oauth-app} -Cuando abres esta página, creemos que ya sabes qué proveedor de identidad social deseas conectar. Lo primero que debes hacer es confirmar que el proveedor de identidad admite el protocolo OAuth, que es un requisito previo para configurar un conector válido. Luego, sigue las instrucciones del proveedor de identidad para registrar y crear la aplicación relevante para la autorización OAuth. +Cuando abras esta página, asumimos que ya sabes a qué proveedor de identidad social deseas conectarte. Lo primero que debes hacer es confirmar que el proveedor de identidad admite el protocolo OAuth, lo cual es un requisito previo para configurar un conector válido. Luego, sigue las instrucciones del proveedor de identidad para registrar y crear la aplicación relevante para la autorización OAuth. ## Configura tu conector \{#configure-your-connector} -SÓLO admitimos el tipo de concesión "Authorization Code" por razones de seguridad y se adapta perfectamente al escenario de Logto. +ÚNICAMENTE admitimos el tipo de concesión "Authorization Code" por motivos de seguridad y se adapta perfectamente al escenario de Logto. -`clientId` y `clientSecret` se pueden encontrar en la página de detalles de tus aplicaciones OAuth. +`clientId` y `clientSecret` se pueden encontrar en la página de detalles de tu aplicación OAuth. -_clientId_: El ID de cliente es un identificador único que identifica la aplicación cliente durante el registro con el servidor de autorización. Este ID es utilizado por el servidor de autorización para verificar la identidad de la aplicación cliente y asociar cualquier token de acceso autorizado con esa aplicación cliente específica. +_clientId_: El client ID es un identificador único que identifica la aplicación cliente durante el registro con el servidor de autorización. Este ID es utilizado por el servidor de autorización para verificar la identidad de la aplicación cliente y asociar cualquier token de acceso autorizado con esa aplicación cliente específica. -_clientSecret_: El secreto de cliente es una clave confidencial que se emite a la aplicación cliente por el servidor de autorización durante el registro. La aplicación cliente utiliza esta clave secreta para autenticarse con el servidor de autorización al solicitar tokens de acceso. El secreto de cliente se considera información confidencial y debe mantenerse seguro en todo momento. +_clientSecret_: El client secret es una clave confidencial que se emite a la aplicación cliente por el servidor de autorización durante el registro. La aplicación cliente utiliza esta clave secreta para autenticarse ante el servidor de autorización al solicitar tokens de acceso. El client secret se considera información confidencial y debe mantenerse seguro en todo momento. -_tokenEndpointAuthMethod_: El método de autenticación del endpoint de token es utilizado por la aplicación cliente para autenticarse con el servidor de autorización al solicitar tokens de acceso. Para descubrir los métodos admitidos, consulta el campo `token_endpoint_auth_methods_supported` disponible en el endpoint de descubrimiento de OpenID Connect del proveedor de servicios OAuth 2.0, o consulta la documentación relevante proporcionada por el proveedor de servicios OAuth 2.0. +_tokenEndpointAuthMethod_: El método de autenticación del endpoint de token es utilizado por la aplicación cliente para autenticarse ante el servidor de autorización al solicitar tokens de acceso. Para descubrir los métodos admitidos, consulta el campo `token_endpoint_auth_methods_supported` disponible en el endpoint de descubrimiento OpenID Connect del proveedor de servicios OAuth 2.0, o consulta la documentación relevante proporcionada por el proveedor de servicios OAuth 2.0. -_clientSecretJwtSigningAlgorithm (Opcional)_: Solo se requiere cuando `tokenEndpointAuthMethod` es `client_secret_jwt`. El algoritmo de firma JWT del secreto de cliente es utilizado por la aplicación cliente para firmar el JWT que se envía al servidor de autorización durante la solicitud de token. +_clientSecretJwtSigningAlgorithm (Opcional)_: Solo es necesario cuando `tokenEndpointAuthMethod` es `client_secret_jwt`. El algoritmo de firma JWT del client secret es utilizado por la aplicación cliente para firmar el JWT que se envía al servidor de autorización durante la solicitud de token. -_scope_: El parámetro de alcance se utiliza para especificar el conjunto de recursos y permisos a los que la aplicación cliente está solicitando acceso. El parámetro de alcance se define típicamente como una lista de valores separados por espacios que representan permisos específicos. Por ejemplo, un valor de alcance de "read write" podría indicar que la aplicación cliente está solicitando acceso de lectura y escritura a los datos de un usuario. +_scope_: El parámetro scope se utiliza para especificar el conjunto de recursos y permisos a los que la aplicación cliente solicita acceso. El parámetro scope suele definirse como una lista de valores separados por espacios que representan permisos específicos. Por ejemplo, un valor de scope "read write" podría indicar que la aplicación cliente solicita acceso de lectura y escritura a los datos de un usuario. Se espera que encuentres `authorizationEndpoint`, `tokenEndpoint` y `userInfoEndpoint` en la documentación del proveedor social. -_authenticationEndpoint_: Este endpoint se utiliza para iniciar el proceso de autenticación. El proceso de autenticación generalmente implica que el usuario inicie sesión y otorgue autorización para que la aplicación cliente acceda a sus recursos. +_authenticationEndpoint_: Este endpoint se utiliza para iniciar el proceso de autenticación. El proceso de autenticación normalmente implica que el usuario inicie sesión y otorgue autorización para que la aplicación cliente acceda a sus recursos. -_tokenEndpoint_: Este endpoint es utilizado por la aplicación cliente para obtener un token de acceso que se puede usar para acceder a los recursos solicitados. La aplicación cliente generalmente envía una solicitud al endpoint de token con un tipo de concesión y un código de autorización para recibir un token de acceso. +_tokenEndpoint_: Este endpoint es utilizado por la aplicación cliente para obtener un token de acceso que puede usarse para acceder a los recursos solicitados. La aplicación cliente normalmente envía una solicitud al endpoint de token con un tipo de concesión y un código de autorización para recibir un token de acceso. -_userInfoEndpoint_: Este endpoint es utilizado por la aplicación cliente para obtener información adicional sobre el usuario, como su nombre completo, dirección de correo electrónico o foto de perfil. El endpoint de información del usuario se accede típicamente después de que la aplicación cliente ha obtenido un token de acceso del endpoint de token. +_userInfoEndpoint_: Este endpoint es utilizado por la aplicación cliente para obtener información adicional sobre el usuario, como su nombre completo, dirección de correo electrónico o foto de perfil. El endpoint de información del usuario normalmente se accede después de que la aplicación cliente ha obtenido un token de acceso del endpoint de token. -Logto también proporciona un campo `profileMap` que los usuarios pueden personalizar para mapear los perfiles de los proveedores sociales que generalmente no son estándar. Las claves son los nombres de los campos de perfil de usuario estándar de Logto y los valores correspondientes deben ser los nombres de los campos de los perfiles sociales. En la etapa actual, Logto solo se preocupa por 'id', 'name', 'avatar', 'email' y 'phone' del perfil social, solo 'id' es un campo requerido y los demás son opcionales. +Logto también proporciona un campo `profileMap` que los usuarios pueden personalizar para mapear los perfiles de los proveedores sociales, que usualmente no son estándar. Las claves son los nombres de los campos estándar del perfil de usuario de Logto y los valores correspondientes deben ser los nombres de los campos del perfil social. En la etapa actual, Logto solo considera 'id', 'name', 'avatar', 'email' y 'phone' del perfil social; solo 'id' es obligatorio y los demás son campos opcionales. -`responseType` y `grantType` SOLO pueden ser valores FIJOS con el tipo de concesión de código de autorización, por lo que los hacemos opcionales y los valores predeterminados se completarán automáticamente. +`responseType` y `grantType` SOLO pueden ser valores FIJOS con el tipo de concesión authorization code, por lo que los hacemos opcionales y los valores predeterminados se completarán automáticamente. -Por ejemplo, puedes encontrar [respuesta de perfil de usuario de Google](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) y, por lo tanto, su `profileMap` debería ser como: +Por ejemplo, puedes encontrar la [respuesta del perfil de usuario de Google](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) y, por lo tanto, su `profileMap` debería ser así: ```json { @@ -41,8 +41,8 @@ Por ejemplo, puedes encontrar [respuesta de perfil de usuario de Google](https:/ :::note -Proporcionamos una clave `customConfig` OPCIONAL para colocar tus parámetros personalizados. -Cada proveedor de identidad social podría tener su propia variante en el protocolo estándar OAuth. Si tu proveedor de identidad social deseado se adhiere estrictamente al protocolo estándar OAuth, entonces no necesitas preocuparte por `customConfig`. +Proporcionamos una clave OPCIONAL `customConfig` para colocar tus parámetros personalizados. +Cada proveedor de identidad social puede tener su propia variante sobre el protocolo estándar OAuth. Si tu proveedor de identidad social deseado se adhiere estrictamente al protocolo estándar OAuth, entonces no necesitas preocuparte por `customConfig`. ::: @@ -62,10 +62,76 @@ Cada proveedor de identidad social podría tener su propia variante en el protoc | customConfig | Record\ | false | | profileMap | ProfileMap | false | -| Campos de ProfileMap | Tipo | Requerido | Valor predeterminado | -| -------------------- | ------ | --------- | -------------------- | -| id | string | false | id | -| name | string | false | name | -| avatar | string | false | avatar | -| email | string | false | email | -| phone | string | false | phone | +| Campos de ProfileMap | Tipo | Requerido | Valor por defecto | +| -------------------- | ------ | --------- | ----------------- | +| id | string | false | id | +| name | string | false | name | +| avatar | string | false | avatar | +| email | string | false | email | +| phone | string | false | phone | + +## Configuraciones generales \{#general-settings} + +Aquí tienes algunas configuraciones generales que no bloquearán la conexión con tu proveedor de identidad, pero pueden afectar la experiencia de autenticación del usuario final. + +### Nombre y logo del botón social \{#social-button-name-and-logo} + +Si deseas mostrar un botón social en tu página de inicio de sesión, puedes establecer el **nombre** y el **logo** (modo oscuro y modo claro) del proveedor de identidad social. Esto ayudará a los usuarios a reconocer la opción de inicio de sesión social. + +### Nombre del proveedor de identidad \{#identity-provider-name} + +Cada conector social tiene un nombre único de Proveedor de Identidad (IdP) para diferenciar las identidades de los usuarios. Mientras que los conectores comunes usan un nombre de IdP fijo, los conectores personalizados requieren un valor único. Aprende más sobre [nombres de IdP](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) para más detalles. + +### Sincronizar información del perfil \{#sync-profile-information} + +En el conector OAuth, puedes establecer la política para sincronizar la información del perfil, como nombres de usuario y avatares. Elige entre: + +- **Solo sincronizar al registrarse**: La información del perfil se obtiene una vez cuando el usuario inicia sesión por primera vez. +- **Siempre sincronizar al iniciar sesión**: La información del perfil se actualiza cada vez que el usuario inicia sesión. + +### Almacenar tokens para acceder a APIs de terceros (Opcional) \{#store-tokens-to-access-third-party-apis-optional} + +Si deseas acceder a las APIs del Proveedor de Identidad y realizar acciones con la autorización del usuario (ya sea mediante inicio de sesión social o vinculación de cuentas), Logto necesita obtener alcances de API específicos y almacenar los tokens. + +1. Añade los alcances requeridos en el campo **scope** siguiendo las instrucciones anteriores. +2. Habilita **Almacenar tokens para acceso persistente a la API** en el conector OAuth de Logto. Logto almacenará de forma segura los tokens de acceso en el Secret Vault. +3. Para proveedores de identidad OAuth/OIDC **estándar**, el alcance `offline_access` debe incluirse para obtener un token de actualización, evitando solicitudes repetidas de consentimiento del usuario. + +:::warning +Mantén tu client secret seguro y nunca lo expongas en el código del lado del cliente. Si se ve comprometido, genera uno nuevo inmediatamente en la configuración de la aplicación de tu proveedor de identidad. +::: + +## Utiliza el conector OAuth \{#utilize-the-oauth-connector} + +Una vez que hayas creado un conector OAuth y lo hayas conectado a tu proveedor de identidad, puedes incorporarlo en tus flujos de usuario final. Elige las opciones que se adapten a tus necesidades: + +### Habilitar el botón de inicio de sesión social \{#enable-social-sign-in-button} + +1. En Logto Console, ve a Experiencia de inicio de sesión > Registro e inicio de sesión. +2. Añade el conector OAuth en la sección **Inicio de sesión social** para permitir que los usuarios se autentiquen con tu proveedor de identidad. + +Aprende más sobre la [experiencia de inicio de sesión social](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular o desvincular una cuenta social \{#link-or-unlink-a-social-account} + +Utiliza la Account API para construir un Centro de Cuenta personalizado en tu aplicación que permita a los usuarios autenticados vincular o desvincular sus cuentas sociales. [Sigue el tutorial de Account API](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Está permitido habilitar el conector OAuth solo para vinculación de cuentas y acceso a la API, sin habilitarlo para inicio de sesión social. +::: + +### Acceder a APIs del proveedor de identidad y realizar acciones \{#access-identity-provider-apis-and-perform-actions} + +Tu aplicación puede recuperar tokens de acceso almacenados desde el Secret Vault para llamar a las APIs de tu proveedor de identidad y automatizar tareas de backend. Las capacidades específicas dependen de tu proveedor de identidad y los alcances que hayas solicitado. Consulta la guía sobre cómo recuperar tokens almacenados para acceso a la API. + +## Gestionar la identidad social del usuario \{#manage-user-s-social-identity} + +Después de que un usuario vincule su cuenta social, los administradores pueden gestionar esa conexión en Logto Console: + +1. Navega a Logto console > Gestión de usuarios y abre el perfil del usuario. +2. En **Conexiones sociales**, localiza el elemento del proveedor de identidad y haz clic en **Gestionar**. +3. En esta página, los administradores pueden gestionar la conexión social del usuario, ver toda la información del perfil otorgada y sincronizada desde su cuenta social, y comprobar el estado del token de acceso. + +:::note +Algunas respuestas de token de acceso del Proveedor de Identidad no incluyen la información específica de los alcances, por lo que Logto no puede mostrar directamente la lista de permisos otorgados por el usuario. Sin embargo, siempre que el usuario haya consentido los alcances solicitados durante la autorización, tu aplicación tendrá los permisos correspondientes al acceder a la API OAuth. +::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index b038d795787..67fc38262f8 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -4,7 +4,7 @@ sidebar_label: OIDC (Social) sidebar_custom_props: description: OpenID Connect 1.0 es una capa de identidad simple sobre el protocolo OAuth 2.0. tutorial_name: OIDC -tutorial_config_name: Aplicación OIDC estándar +tutorial_config_name: Standard OIDC app --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -19,11 +19,21 @@ El conector oficial de Logto para el protocolo OpenID Connect (OIDC). ## Comenzar \{#get-started} -El conector OIDC permite la conexión de Logto a un proveedor de identidad social arbitrario que admite el protocolo OIDC. +El conector OIDC permite la conexión de Logto con cualquier proveedor de identidad social que admita el protocolo OIDC. Utiliza el conector OIDC para que tu aplicación pueda: + +- Añadir botones de inicio de sesión social +- Vincular cuentas de usuario a identidades sociales +- Sincronizar la información del perfil del usuario desde el proveedor social +- Acceder a APIs de terceros mediante el almacenamiento seguro de tokens en Logto Secret Vault para tareas de automatización (por ejemplo, editar Google Docs, gestionar eventos de Calendario en tu aplicación) + +Para configurar estas funciones de autenticación, primero crea un conector OIDC en Logto: + +1. Ve a Consola de Logto > Conector > Conector social. +2. Haz clic en **Agregar conector social**, selecciona **OIDC**, haz clic en **Siguiente** y sigue el tutorial paso a paso para completar la integración. :::note -El conector OIDC es un tipo especial de conector en Logto, puedes agregar algunos conectores basados en OIDC. +El conector OIDC es un tipo especial de conector en Logto; puedes agregar múltiples conectores basados en el protocolo OIDC. ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index 9d00bdbf5d9..01e0eecd6b0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,45 +1,45 @@ ## Crea tu aplicación OIDC \{#create-your-oidc-app} -Cuando abres esta página, creemos que ya sabes qué proveedor de identidad social deseas conectar. Lo primero que debes hacer es confirmar que el proveedor de identidad admite el protocolo OIDC, que es un requisito previo para configurar un conector válido. Luego, sigue las instrucciones del proveedor de identidad para registrar y crear la aplicación relevante para la autorización OIDC. +Cuando abres esta página, asumimos que ya sabes qué proveedor de identidad social deseas conectar. Lo primero que debes hacer es confirmar que el proveedor de identidad admite el protocolo OIDC, lo cual es un requisito previo para configurar un conector válido. Luego, sigue las instrucciones del proveedor de identidad para registrar y crear la aplicación relevante para la autorización OIDC. ## Configura tu conector \{#configure-your-connector} -SOLO admitimos el tipo de concesión "Authorization Code" por razones de seguridad y se adapta perfectamente al escenario de Logto. +ÚNICAMENTE admitimos el tipo de concesión "Authorization Code" por motivos de seguridad y se adapta perfectamente al escenario de Logto. -`clientId` y `clientSecret` se pueden encontrar en la página de detalles de tus aplicaciones OIDC. +`clientId` y `clientSecret` se pueden encontrar en la página de detalles de tu aplicación OIDC. -_clientId_: El ID de cliente es un identificador único que identifica la aplicación cliente durante el registro con el servidor de autorización. Este ID es utilizado por el servidor de autorización para verificar la identidad de la aplicación cliente y asociar cualquier token de acceso autorizado con esa aplicación cliente específica. +_clientId_: El client ID es un identificador único que identifica la aplicación cliente durante el registro con el servidor de autorización. Este ID es utilizado por el servidor de autorización para verificar la identidad de la aplicación cliente y asociar cualquier token de acceso autorizado con esa aplicación cliente específica. -_clientSecret_: El secreto de cliente es una clave confidencial que se emite a la aplicación cliente por el servidor de autorización durante el registro. La aplicación cliente utiliza esta clave secreta para autenticarse con el servidor de autorización al solicitar tokens de acceso. El secreto de cliente se considera información confidencial y debe mantenerse seguro en todo momento. +_clientSecret_: El client secret es una clave confidencial que se emite a la aplicación cliente por el servidor de autorización durante el registro. La aplicación cliente utiliza esta clave secreta para autenticarse con el servidor de autorización al solicitar tokens de acceso. El client secret se considera información confidencial y debe mantenerse seguro en todo momento. -_tokenEndpointAuthMethod_: El método de autenticación del endpoint de token es utilizado por la aplicación cliente para autenticarse con el servidor de autorización al solicitar tokens de acceso. Para descubrir los métodos admitidos, consulta el campo `token_endpoint_auth_methods_supported` disponible en el endpoint de descubrimiento de OpenID Connect del proveedor de servicios OAuth 2.0, o consulta la documentación relevante proporcionada por el proveedor de servicios OAuth 2.0. +_tokenEndpointAuthMethod_: El método de autenticación del endpoint de token es utilizado por la aplicación cliente para autenticarse con el servidor de autorización al solicitar tokens de acceso. Para descubrir los métodos admitidos, consulta el campo `token_endpoint_auth_methods_supported` disponible en el endpoint de descubrimiento OpenID Connect del proveedor de servicios OAuth 2.0, o consulta la documentación relevante proporcionada por el proveedor de servicios OAuth 2.0. -_clientSecretJwtSigningAlgorithm (Opcional)_: Solo se requiere cuando `tokenEndpointAuthMethod` es `client_secret_jwt`. El algoritmo de firma JWT del secreto de cliente es utilizado por la aplicación cliente para firmar el JWT que se envía al servidor de autorización durante la solicitud de token. +_clientSecretJwtSigningAlgorithm (Opcional)_: Solo es necesario cuando `tokenEndpointAuthMethod` es `client_secret_jwt`. El algoritmo de firma JWT del client secret es utilizado por la aplicación cliente para firmar el JWT que se envía al servidor de autorización durante la solicitud de token. -_scope_: El parámetro de alcance se utiliza para especificar el conjunto de recursos y permisos a los que la aplicación cliente está solicitando acceso. El parámetro de alcance se define típicamente como una lista de valores separados por espacios que representan permisos específicos. Por ejemplo, un valor de alcance de "read write" podría indicar que la aplicación cliente está solicitando acceso de lectura y escritura a los datos de un usuario. +_scope_: El parámetro scope se utiliza para especificar el conjunto de recursos y permisos a los que la aplicación cliente solicita acceso. El parámetro scope suele definirse como una lista de valores separados por espacios que representan permisos específicos. Por ejemplo, un valor de scope "read write" podría indicar que la aplicación cliente solicita acceso de lectura y escritura a los datos de un usuario. -Se espera que encuentres `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` y `issuer` como información de configuración del Proveedor de OpenID. Deberían estar disponibles en la documentación del proveedor social. +Se espera que encuentres `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` y `issuer` como información de configuración del Proveedor OpenID. Deberían estar disponibles en la documentación del proveedor social. -_authenticationEndpoint_: Este endpoint se utiliza para iniciar el proceso de autenticación. El proceso de autenticación generalmente implica que el usuario inicie sesión y otorgue autorización para que la aplicación cliente acceda a sus recursos. +_authenticationEndpoint_: Este endpoint se utiliza para iniciar el proceso de autenticación. El proceso de autenticación normalmente implica que el usuario inicie sesión y otorgue autorización para que la aplicación cliente acceda a sus recursos. -_tokenEndpoint_: Este endpoint es utilizado por la aplicación cliente para obtener un token de ID que se puede usar para acceder a los recursos solicitados. La aplicación cliente generalmente envía una solicitud al endpoint de token con un tipo de concesión y un código de autorización para recibir un token de ID. +_tokenEndpoint_: Este endpoint es utilizado por la aplicación cliente para obtener un token de ID que puede usarse para acceder a los recursos solicitados. La aplicación cliente normalmente envía una solicitud al endpoint de token con un tipo de concesión y un código de autorización para recibir un token de ID. -_jwksUri_: Este es el endpoint URL donde se puede obtener el Conjunto de Claves Web JSON (JWKS) del proveedor de identidad social (abreviado como IdP). El JWKS es un conjunto de claves criptográficas que el IdP utiliza para firmar y verificar JSON Web Tokens (JWTs) que se emiten durante el proceso de autenticación. El `jwksUri` es utilizado por la parte confiable (RP) para obtener las claves públicas utilizadas por el IdP para firmar los JWTs, de modo que la RP pueda verificar la autenticidad e integridad de los JWTs recibidos del IdP. +_jwksUri_: Esta es la URL del endpoint donde se puede obtener el JSON Web Key Set (JWKS) del proveedor de identidad social (IdP). El JWKS es un conjunto de claves criptográficas que el IdP utiliza para firmar y verificar los JSON Web Tokens (JWTs) que se emiten durante el proceso de autenticación. El `jwksUri` es utilizado por la parte confiable (RP) para obtener las claves públicas utilizadas por el IdP para firmar los JWTs, de modo que la RP pueda verificar la autenticidad e integridad de los JWTs recibidos del IdP. -_issuer_: Este es el identificador único del IdP que es utilizado por la RP para verificar los JWTs recibidos del IdP. Se incluye en los JWTs como el [reclamo](https://www.rfc-editor.org/rfc/rfc7519#section-4) `iss` (el token de ID siempre es un JWT). El valor del emisor debe coincidir con la URL del servidor de autorización del IdP, y debe ser un URI en el que la RP confíe. Cuando la RP recibe un JWT, verifica el reclamo `iss` para asegurarse de que fue emitido por un IdP confiable y que el JWT está destinado a ser utilizado con la RP. +_issuer_: Este es el identificador único del IdP que es utilizado por la RP para verificar los JWTs recibidos del IdP. Se incluye en los JWTs como el [reclamo (claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4) `iss` (el token de ID siempre es un JWT). El valor de issuer debe coincidir con la URL del servidor de autorización del IdP, y debe ser un URI en el que la RP confíe. Cuando la RP recibe un JWT, verifica el reclamo `iss` para asegurarse de que fue emitido por un IdP confiable y que el JWT está destinado a ser utilizado con la RP. -Juntos, `jwksUri` y `issuer` proporcionan un mecanismo seguro para que la RP verifique la identidad del usuario final durante el proceso de autenticación. Al usar las claves públicas obtenidas del `jwksUri`, la RP puede verificar la autenticidad e integridad de los JWTs emitidos por el IdP. El valor del emisor asegura que la RP solo acepte JWTs que fueron emitidos por un IdP confiable y que los JWTs están destinados a ser utilizados con la RP. +Juntos, `jwksUri` y `issuer` proporcionan un mecanismo seguro para que la RP verifique la identidad del usuario final durante el proceso de autenticación. Al usar las claves públicas obtenidas del `jwksUri`, la RP puede verificar la autenticidad e integridad de los JWTs emitidos por el IdP. El valor de issuer garantiza que la RP solo acepte JWTs que hayan sido emitidos por un IdP confiable y que los JWTs estén destinados a ser utilizados con la RP. -Dado que siempre se requiere una solicitud de autenticación, se proporciona un `authRequestOptionalConfig` para envolver todas las configuraciones opcionales, puedes encontrar detalles en [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). También puedes notar que `nonce` falta en esta configuración. Dado que `nonce` debe ser idéntico para cada solicitud, colocamos la generación de `nonce` en la implementación del código. ¡Así que no te preocupes por ello! Los mencionados anteriormente `jwksUri` y `issuer` también están incluidos en `idTokenVerificationConfig`. +Dado que siempre se requiere una solicitud de autenticación, se proporciona un `authRequestOptionalConfig` para agrupar todas las configuraciones opcionales. Puedes encontrar detalles en [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). También puedes notar que `nonce` no está presente en esta configuración. Dado que `nonce` debe ser idéntico para cada solicitud, colocamos la generación de `nonce` en la implementación del código. ¡Así que no te preocupes por ello! Los ya mencionados `jwksUri` y `issuer` también están incluidos en `idTokenVerificationConfig`. -Puede que te preguntes por qué un protocolo OIDC estándar admite tanto los flujos implícitos como los híbridos, pero el conector de Logto solo admite el flujo de autorización. Se ha determinado que los flujos implícitos e híbridos son menos seguros que el flujo de autorización. Debido al enfoque de Logto en la seguridad, solo admite el flujo de autorización para el nivel más alto de seguridad para sus usuarios, a pesar de su naturaleza ligeramente menos conveniente. +Quizás te preguntes por qué un protocolo OIDC estándar admite tanto los flujos implícitos como los híbridos, pero el conector de Logto solo admite el flujo de autorización. Se ha determinado que los flujos implícitos e híbridos son menos seguros que el flujo de autorización. Debido al enfoque de Logto en la seguridad, solo admite el flujo de autorización para ofrecer el mayor nivel de seguridad a sus usuarios, a pesar de su naturaleza ligeramente menos conveniente. -`responseType` y `grantType` SOLO pueden ser valores FIJOS con el flujo de "Authorization Code", por lo que los hacemos opcionales y los valores predeterminados se completarán automáticamente. +`responseType` y `grantType` SOLO pueden ser valores FIJOS con el flujo "Authorization Code", por lo que los hacemos opcionales y los valores predeterminados se completarán automáticamente. :::note -Para todos los tipos de flujo, proporcionamos una clave `customConfig` OPCIONAL para colocar tus parámetros personalizados. -Cada proveedor de identidad social podría tener su propia variante en el protocolo estándar OIDC. Si tu proveedor de identidad social deseado se adhiere estrictamente al protocolo estándar OIDC, entonces no necesitas preocuparte por `customConfig`. +Para todos los tipos de flujo, proporcionamos una clave OPCIONAL `customConfig` para colocar tus parámetros personalizados. +Cada proveedor de identidad social puede tener su propia variante sobre el protocolo estándar OIDC. Si tu proveedor de identidad social deseado se adhiere estrictamente al protocolo estándar OIDC, entonces no necesitas preocuparte por `customConfig`. ::: @@ -83,3 +83,69 @@ Cada proveedor de identidad social podría tener su propia variante en el protoc | typ | string | False | Consulta [aquí](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) para encontrar más detalles sobre `IdTokenVerificationConfig`. + +## Configuración general \{#general-settings} + +Aquí tienes algunas configuraciones generales que no bloquearán la conexión con tu proveedor de identidad, pero pueden afectar la experiencia de autenticación del usuario final. + +### Nombre y logo del botón social \{#social-button-name-and-logo} + +Si deseas mostrar un botón social en tu página de inicio de sesión, puedes establecer el **nombre** y el **logo** (modo oscuro y modo claro) del proveedor de identidad social. Esto ayudará a los usuarios a reconocer la opción de inicio de sesión social. + +### Nombre del proveedor de identidad \{#identity-provider-name} + +Cada conector social tiene un nombre único de Proveedor de Identidad (IdP) para diferenciar las identidades de los usuarios. Mientras que los conectores comunes usan un nombre de IdP fijo, los conectores personalizados requieren un valor único. Aprende más sobre [nombres de IdP](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) para más detalles. + +### Sincronizar información de perfil \{#sync-profile-information} + +En el conector OIDC, puedes establecer la política para sincronizar la información del perfil, como nombres de usuario y avatares. Elige entre: + +- **Sincronizar solo al registrarse**: La información del perfil se obtiene una vez cuando el usuario inicia sesión por primera vez. +- **Sincronizar siempre al iniciar sesión**: La información del perfil se actualiza cada vez que el usuario inicia sesión. + +### Almacenar tokens para acceder a APIs de terceros (Opcional) \{#store-tokens-to-access-third-party-apis-optional} + +Si deseas acceder a las APIs del Proveedor de Identidad y realizar acciones con la autorización del usuario (ya sea mediante inicio de sesión social o vinculación de cuenta), Logto necesita obtener los alcances de API específicos y almacenar los tokens. + +1. Agrega los alcances requeridos en el campo **scope** siguiendo las instrucciones anteriores. +2. Habilita **Almacenar tokens para acceso persistente a la API** en el conector OIDC de Logto. Logto almacenará de forma segura los tokens de acceso en el Secret Vault. +3. Para proveedores de identidad OAuth/OIDC **estándar**, el alcance `offline_access` debe incluirse para obtener un token de actualización, evitando solicitudes repetidas de consentimiento del usuario. + +:::warning +Mantén tu client secret seguro y nunca lo expongas en el código del lado del cliente. Si se ve comprometido, genera uno nuevo inmediatamente en la configuración de la aplicación de tu proveedor de identidad. +::: + +## Utiliza el conector OIDC \{#utilize-the-oidc-connector} + +Una vez que hayas creado un conector OIDC y lo hayas conectado a tu proveedor de identidad, puedes incorporarlo en tus flujos de usuario final. Elige las opciones que se adapten a tus necesidades: + +### Habilitar botón de inicio de sesión social \{#enable-social-sign-in-button} + +1. En Logto Console, ve a Experiencia de inicio de sesión > Registro e inicio de sesión. +2. Agrega el conector OIDC en la sección **Inicio de sesión social** para permitir que los usuarios se autentiquen con tu proveedor de identidad. + +Aprende más sobre la [experiencia de inicio de sesión social](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular o desvincular una cuenta social \{#link-or-unlink-a-social-account} + +Utiliza la Account API para construir un Centro de Cuenta personalizado en tu aplicación que permita a los usuarios autenticados vincular o desvincular sus cuentas sociales. [Sigue el tutorial de Account API](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Está permitido habilitar el conector OIDC solo para vinculación de cuentas y acceso a la API, sin habilitarlo para inicio de sesión social. +::: + +### Acceder a APIs del proveedor de identidad y realizar acciones \{#access-identity-provider-apis-and-perform-actions} + +Tu aplicación puede recuperar los tokens de acceso almacenados desde el Secret Vault para llamar a las APIs de tu proveedor de identidad y automatizar tareas en el backend. Las capacidades específicas dependen de tu proveedor de identidad y los alcances que hayas solicitado. Consulta la guía sobre cómo recuperar tokens almacenados para acceso a la API. + +## Gestionar la identidad social del usuario \{#manage-user-s-social-identity} + +Después de que un usuario vincule su cuenta social, los administradores pueden gestionar esa conexión en Logto Console: + +1. Navega a Logto console > Gestión de usuarios y abre el perfil del usuario. +2. En **Conexiones sociales**, localiza el elemento del proveedor de identidad y haz clic en **Gestionar**. +3. En esta página, los administradores pueden gestionar la conexión social del usuario, ver toda la información de perfil concedida y sincronizada desde su cuenta social, y comprobar el estado del token de acceso. + +:::note +Algunas respuestas de token de acceso del Proveedor de Identidad no incluyen la información específica de los alcances, por lo que Logto no puede mostrar directamente la lista de permisos concedidos por el usuario. Sin embargo, siempre que el usuario haya consentido los alcances solicitados durante la autorización, tu aplicación tendrá los permisos correspondientes al acceder a la API OIDC. +::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index bfe2e77dbc4..25315ea7003 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: Gestión unificada y segura del acceso de usuarios dentro del ecosistema de Google. + description: Gestión unificada y segura del acceso de usuarios dentro del ecosistema de Google. (Unified and secure management of user access within the Google ecosystem.) logoFilename: 'google.svg' tutorial_name: Google Workspace enterprise SSO tutorial_config_name: Google Cloud Platform @@ -16,10 +16,11 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -# Configura el inicio de sesión único con Google Workspace +# Configura el inicio de sesión único con Google Workspace (Set up Single Sign-On with Google Workspace) -Con un mínimo esfuerzo de configuración, este conector permite la integración con Microsoft Entra ID para SSO empresarial. +Con un esfuerzo mínimo de configuración, este conector permite la integración con Microsoft Entra ID para SSO empresarial. @@ -35,14 +36,18 @@ Con un mínimo esfuerzo de configuración, este conector permite la integración -## Paso 4: Configura el conector de Logto con las credenciales del cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} +## Paso 4: Configura el conector de Logto con las credenciales de cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} -## Paso 5: Alcances adicionales (Opcional) \{#step-5-additional-scopes-optional} +## Paso 5: Alcances adicionales (opcional) \{#step-5-additional-scopes-optional} -## Paso 6: Establece dominios de correo electrónico y habilita el conector SSO \{#step-6-set-email-domains-and-enable-the-sso-connector} +## Paso 6: Almacena tokens para acceder a las APIs de Google (opcional) \{#step-6-store-tokens-to-access-google-apis-optional} + +## Paso 7: Establece los dominios de correo electrónico y habilita el conector SSO \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index d555e127898..ce1f5321ada 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,6 +4,7 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; ### Paso 1: Crea un nuevo proyecto en Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} @@ -17,14 +18,18 @@ import Step6 from './_step-6.mdx'; -### Paso 4: Configura el conector Logto con las credenciales del cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} +### Paso 4: Configura el conector de Logto con las credenciales del cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} -### Paso 5: Alcances adicionales (Opcional) \{#step-5-additional-scopes-optional} +### Paso 5: Alcances adicionales (opcional) \{#step-5-additional-scopes-optional} -### Paso 6: Establece dominios de correo electrónico y habilita el conector SSO \{#step-6-set-email-domains-and-enable-the-sso-connector} +### Paso 6: Almacena tokens para acceder a las APIs de Google (opcional) \{#step-6-store-tokens-to-access-google-apis-optional} + +### Paso 7: Establece dominios de correo electrónico y habilita el conector SSO \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index b9e4e0a22e8..fea109584b1 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -Usa el campo `Scope` para añadir alcances adicionales a tu solicitud de OAuth. Esto te permitirá solicitar más información del servidor OAuth de Google. Por favor, consulta la documentación de [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) para más información. +Los alcances (Scopes) definen los permisos que tu aplicación solicita a los usuarios y controlan a qué datos puede acceder tu aplicación desde sus cuentas de Google Workspace. Solicitar permisos de Google requiere configuración en ambos lados: -Independientemente de la configuración de alcances personalizados, Logto siempre enviará los alcances `openid`, `profile` y `email` al IdP. Esto es para asegurar que Logto pueda recuperar correctamente la información de identidad del usuario y la dirección de correo electrónico. +**En Google Cloud Console:** + +1. Navega a **APIs & Services > OAuth consent screen > Scopes**. +2. Haz clic en **Add or Remove Scopes** y selecciona solo los alcances que tu aplicación requiere: + - Autenticación (Authentication) (Obligatorio): + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - Acceso a API (Opcional): Añade cualquier alcance adicional necesario para tu aplicación (por ejemplo, Drive, Calendar, YouTube). Explora la [Biblioteca de API de Google](https://console.cloud.google.com/apis/library) para encontrar los servicios disponibles. Si tu aplicación necesita acceso a APIs de Google más allá de los permisos básicos, primero habilita las APIs específicas que tu aplicación utilizará (por ejemplo, Google Drive API, Gmail API, Calendar API) en la Biblioteca de API de Google. +3. Haz clic en **Update** para confirmar la selección. +4. Haz clic en **Save and Continue** para aplicar los cambios. + +**En el conector de Google Workspace de Logto:** + +1. Logto incluye automáticamente los alcances `openid`, `profile` y `email` para recuperar la información básica de identidad del usuario. Puedes dejar el campo `Scopes` en blanco si solo necesitas información básica del usuario. +2. Añade alcances adicionales (separados por espacios) en el campo `Scopes` para solicitar más datos de Google. Usa URLs completas de alcance, por ejemplo: `https://www.googleapis.com/auth/calendar.readonly` + +:::tip +Si tu aplicación solicita estos alcances para acceder a la API de Google y realizar acciones, asegúrate de habilitar **Store tokens for persistent API access** en el conector de Google de Logto. Consulta la siguiente sección para más detalles. +::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index b9073c358b8..d1252eeb809 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -Proporciona los `dominios de correo electrónico` de tu organización en la pestaña de `experiencia SSO` del conector de Logto. Esto habilitará el conector SSO como un método de autenticación para esos usuarios. +Si deseas acceder a [APIs de Google](https://console.cloud.google.com/apis/library) y realizar acciones con autorización del usuario, Logto necesita obtener alcances de API (Scopes) específicos y almacenar tokens. -Los usuarios con direcciones de correo electrónico en los dominios especificados serán redirigidos para usar tu conector SSO como su único método de autenticación. +1. Añade los alcances requeridos en la configuración de la pantalla de consentimiento OAuth de tu Google Cloud Console y en el conector de Google de Logto. +2. Habilita **Almacenar tokens para acceso persistente a la API** en el conector de Google de Logto. Logto almacenará de forma segura los tokens de acceso y actualización de Google en el Secret Vault. +3. Para asegurar que se devuelvan tokens de actualización, configura tu conector de Google de Logto para habilitar el **Acceso sin conexión (Offline Access)**. -Para obtener más información sobre el conector SSO de Google Workspace, por favor consulta [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). +:::warning +No necesitas añadir `offline_access` en el campo `Scope` de Logto — hacerlo puede causar un error. Google utiliza `access_type=offline` automáticamente cuando el acceso sin conexión está habilitado. +::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..e237c9ec674 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +Proporciona los `dominios de correo electrónico` de tu organización en la pestaña de `experiencia SSO` del conector de Logto. Esto habilitará el conector SSO como un método de autenticación para esos usuarios. + +Los usuarios con direcciones de correo electrónico en los dominios especificados serán redirigidos para usar tu conector SSO como su único método de autenticación. + +Para obtener más información sobre el conector SSO de Google Workspace, consulta [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 4ef45b6b64c..61ad23b34d0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -2,10 +2,10 @@ slug: /integrations/oidc-sso sidebar_label: OIDC (Enterprise) sidebar_custom_props: - description: Protocolo moderno construido sobre OAuth 2.0 para la verificación de identidad en aplicaciones web y móviles. + description: Protocolo moderno basado en OAuth 2.0 para la verificación de identidad en aplicaciones web y móviles. (Modern protocol built on OAuth 2.0 for identity verification in web and mobile apps.) logoFilename: 'oidc.svg' tutorial_name: OIDC enterprise SSO -tutorial_config_name: Aplicación OIDC en tu IdP +tutorial_config_name: OIDC application on your IdP --- import GuideTip from '../../fragments/_sso_guide_tip.mdx'; @@ -13,10 +13,12 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; -# Configura el inicio de sesión único con OpenID Connect (OIDC) +# Configura el inicio de sesión único con OpenID Connect (OIDC) (Set up Single Sign-On with OpenID Connect (OIDC)) -Con un mínimo esfuerzo de configuración, este conector permite la integración con cualquier Proveedor de Identidad (IdP) basado en OIDC. +Con un esfuerzo mínimo de configuración, este conector permite la integración con cualquier proveedor de identidad (IdP) basado en OIDC. @@ -28,6 +30,14 @@ Con un mínimo esfuerzo de configuración, este conector permite la integración -## Paso 3: Establece dominios de correo electrónico y habilita el conector SSO \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Paso 3: Configura alcances (opcional) (Configure scopes (Optional)) \{#step-3-configure-scopes-optional} + +## Paso 4: Almacena tokens para acceder a APIs de terceros (opcional) (Store tokens to access third-party APIs (Optional)) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Paso 5: Establece dominios de correo electrónico y habilita el conector SSO (Set email domains and enable the SSO connector) \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index 1a88ab2d250..b9fcc7e79cc 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,6 +1,8 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; ### Paso 1: Crea una aplicación OIDC en tu IdP \{#step-1-create-an-oidc-application-on-your-idp} @@ -10,6 +12,14 @@ import Step3 from './_step-3.mdx'; -### Paso 3: Establece dominios de correo electrónico y habilita el conector SSO \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Paso 3: Configura alcances (Scopes) (Opcional) \{#step-3-configure-scopes-optional} + +## Paso 4: Almacena tokens para acceder a APIs de terceros (Opcional) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Paso 5: Establece dominios de correo electrónico y habilita el conector SSO \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index a41abfe7be5..c37b9e49e1a 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -Después de crear con éxito una aplicación OIDC en el lado del IdP, necesitarás proporcionar las configuraciones del IdP de vuelta a Logto. Navega a la pestaña `Connection` y completa las siguientes configuraciones: +Después de crear exitosamente una aplicación OIDC en el lado del proveedor de identidad (IdP), deberás proporcionar las configuraciones del IdP de vuelta a Logto. Navega a la pestaña `Connection` y completa las siguientes configuraciones: - **Client ID**: Un identificador único asignado a tu aplicación OIDC por el IdP. Este identificador es utilizado por Logto para identificar y autenticar la aplicación durante el flujo OIDC. - **Client Secret**: Un secreto confidencial compartido entre Logto y el IdP. Este secreto se utiliza para autenticar la aplicación OIDC y asegurar la comunicación entre Logto y el IdP. -- **Emisor (Issuer)**: La URL del emisor, un identificador único para el IdP, que especifica la ubicación donde se puede encontrar el proveedor de identidad OIDC. Es una parte crucial de la configuración OIDC ya que ayuda a Logto a descubrir los endpoints necesarios. - Para facilitar el proceso de configuración, Logto obtendrá automáticamente los endpoints y configuraciones OIDC requeridos. Esto se hace utilizando el emisor que proporcionaste y realizando una llamada a los endpoints de descubrimiento OIDC del IdP. Es imperativo asegurarse de que el endpoint del emisor sea válido y esté configurado correctamente para permitir que Logto recupere la información requerida correctamente. +- **Emisor (Issuer)**: La URL del emisor, un identificador único para el IdP, que especifica la ubicación donde se puede encontrar el proveedor de identidad OIDC. Es una parte crucial de la configuración OIDC, ya que ayuda a Logto a descubrir los endpoints necesarios. + Para facilitar el proceso de configuración, Logto obtendrá automáticamente los endpoints y configuraciones OIDC requeridos. Esto se realiza utilizando el emisor que proporcionaste y haciendo una llamada a los endpoints de descubrimiento OIDC del IdP. Es imprescindible asegurarse de que el endpoint del emisor sea válido y esté configurado correctamente para permitir que Logto recupere la información necesaria de manera correcta. Después de una solicitud de obtención exitosa, deberías poder ver las configuraciones del IdP analizadas en la sección de emisores. -- **Alcance (Scope)**: Una lista de cadenas separadas por espacios que define los permisos o niveles de acceso deseados solicitados por Logto durante el proceso de autenticación OIDC. El parámetro de alcance te permite especificar qué información y acceso está solicitando Logto del IdP. - El parámetro de alcance es opcional. Independientemente de la configuración de alcance personalizada, Logto siempre enviará los alcances `openid`, `profile` y `email` al IdP. - Esto es para asegurar que Logto pueda recuperar correctamente la información de identidad del usuario y la dirección de correo electrónico del IdP. Puedes agregar alcances adicionales al parámetro de alcance para solicitar más información del IdP. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index 5a97ba89c58..17ac6b16d73 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -Proporciona los `dominios de correo electrónico` de tu organización en la pestaña de `experiencia SSO` del conector de Logto. Esto habilitará el conector SSO como un método de autenticación para esos usuarios. +Los alcances (Scopes) definen los permisos que tu aplicación solicita a los usuarios y controlan a qué datos puede acceder tu aplicación desde sus cuentas empresariales. -Los usuarios con direcciones de correo electrónico en los dominios especificados serán redirigidos para usar tu conector SSO como su único método de autenticación. +Configurar los alcances requiere ajustes en ambos lados: + +1. **Tu proveedor de identidad (IdP) (Identity Provider)**: Configura qué permisos están permitidos para la autorización en la consola de tu IdP + - Algunos IdP habilitan todos los alcances públicos por defecto (no se requiere acción) + - Otros requieren que otorgues permisos explícitamente +2. **Conector empresarial de Logto**: Especifica qué alcances solicitar durante la autenticación en la configuración del conector empresarial OIDC de Logto > campo `Scopes`. + - Logto siempre incluye los alcances `openid`, `profile` y `email` para recuperar información básica de identidad del usuario, independientemente de tus configuraciones personalizadas de alcance. + - Puedes añadir alcances adicionales (separados por espacios) para solicitar más información al IdP. + +:::tip +Si tu aplicación necesita acceder a APIs utilizando estos alcances, asegúrate de habilitar **Almacenar tokens para acceso persistente a la API** en tu conector empresarial de Logto. Consulta la siguiente sección para más detalles. +::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..232e8736319 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +Si deseas acceder a las API del Proveedor de Identidad (Identity Provider) y realizar acciones con autorización del usuario, Logto necesita obtener alcances (scopes) específicos de API y almacenar tokens. + +1. Añade los alcances requeridos en el campo **scope** siguiendo las instrucciones anteriores. +2. Activa **Almacenar tokens para acceso persistente a la API** en el conector empresarial OIDC de Logto. Logto almacenará de forma segura los tokens de acceso (access tokens) en el Secret Vault. +3. Para los proveedores de identidad OIDC **estándar**, el alcance `offline_access` debe ser incluido para obtener un token de actualización (refresh token), evitando así solicitudes repetidas de consentimiento del usuario. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..5a97ba89c58 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +Proporciona los `dominios de correo electrónico` de tu organización en la pestaña de `experiencia SSO` del conector de Logto. Esto habilitará el conector SSO como un método de autenticación para esos usuarios. + +Los usuarios con direcciones de correo electrónico en los dominios especificados serán redirigidos para usar tu conector SSO como su único método de autenticación. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index d72e25c1327..c005a4a321f 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -4,43 +4,47 @@ sidebar_position: 2 # Despliegue y configuración -En el artículo anterior, cubrimos los conceptos básicos de [comenzar rápidamente con Logto](/logto-oss/get-started-with-oss). Este artículo profundiza más, centrándose en las mejores prácticas y pasos detallados de configuración para desplegar Logto en un entorno de producción. +En el artículo anterior, cubrimos lo básico sobre [cómo empezar rápidamente con Logto](/logto-oss/get-started-with-oss). Este artículo profundiza más, enfocándose en las mejores prácticas y pasos detallados de configuración para desplegar Logto en un entorno de producción. ## Variables de entorno \{#environment-variables} -Usamos un conjunto predefinido de variables de entorno en nuestra demostración (`docker-compose.yml`), que deberías reemplazar con las tuyas y mantener la consistencia en múltiples instancias de Logto. +Utilizamos un conjunto predefinido de variables de entorno generado en nuestra demo (`docker-compose.yml`), que deberías reemplazar por las tuyas propias y mantener la coherencia entre múltiples instancias de Logto. -Puedes establecer las variables de entorno directamente o colocar un archivo `.env` dentro de la raíz del proyecto Logto. Si estás probando con Docker, revisa el `.env` generado de la imagen en `/etc/logto`. +Puedes establecer las variables de entorno directamente o poner un archivo `.env` dentro de la raíz del proyecto Logto. Si estás probando con Docker, revisa el archivo `.env` generado de la imagen en `/etc/logto`. ### Esenciales \{#essentials} - `DB_URL` El [DSN de Postgres](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para la base de datos de Logto. -- `PORT` El puerto al que Logto escucha. Por defecto `3001`. -- `ENDPOINT` Puedes especificar una URL con tu dominio personalizado para producción (Ej. `ENDPOINT=https://logto.domain.com`). Esto también afectará el valor del [identificador del emisor de OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). +- `PORT` El puerto en el que Logto escucha. Por defecto `3001`. +- `ENDPOINT` Puedes especificar una URL con tu dominio personalizado para producción (Ejemplo: `ENDPOINT=https://logto.domain.com`). Esto también afectará el valor del [identificador de emisor OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). **Habilitar la Consola de Administración** -- `ADMIN_PORT` El puerto al que la Consola de Administración de Logto escucha. Por defecto `3002`. -- `ADMIN_ENDPOINT` Puedes especificar una URL con tu dominio personalizado para producción (Ej. `ADMIN_ENDPOINT=https://admin.domain.com`). Esto también afectará el valor de los URIs de redirección de la Consola de Administración. +- `ADMIN_PORT` El puerto en el que la Consola de Administración de Logto escucha. Por defecto `3002`. +- `ADMIN_ENDPOINT` Puedes especificar una URL con tu dominio personalizado para producción (Ejemplo: `ADMIN_ENDPOINT=https://admin.domain.com`). Esto también afectará el valor de las URIs de redirección de la Consola de Administración. **Deshabilitar la Consola de Administración** -- `ADMIN_DISABLE_LOCALHOST` Establécelo en `1` o `true` para cerrar el puerto de la Consola de Administración. Si `ADMIN_ENDPOINT` no está configurado, deshabilitará completamente la Consola de Administración. +- `ADMIN_DISABLE_LOCALHOST` Establécelo en `1` o `true` para cerrar el puerto de la Consola de Administración. Si `ADMIN_ENDPOINT` no está establecido, deshabilitará completamente la Consola de Administración. Para más detalles sobre las variables de entorno, consulta [Configuración](/concepts/core-service/configuration/). +**Habilitar Secret Vault** + +- Para usar el [Secret Vault](/secret-vault), necesitas establecer `SECRET_VAULT_KEK` con una cadena codificada en base64 de tu Key Encryption Key (KEK). Esto se utiliza para cifrar las Data Encryption Keys (DEK) en el Secret Vault. Se recomienda AES-256 (32 bytes). Ejemplo: `crypto.randomBytes(32).toString('base64')`. + ### HTTPS \{#https} -Puedes usar Node.js para servir HTTPS directamente o configurar un proxy / balanceador HTTPS frente a Node.js. Consulta [Habilitar HTTPS](/concepts/core-service/configuration/#enabling-https) para más detalles. +Puedes usar Node.js para servir HTTPS directamente o configurar un proxy / balanceador HTTPS delante de Node.js. Consulta [Habilitar HTTPS](/concepts/core-service/configuration/#enabling-https) para más detalles. ### Proxy inverso \{#reverse-proxy} -Si deseas usar un proxy inverso en tu servidor, por ejemplo Nginx o Apache, necesitas mapear los puertos 3001 y 3002 por separado en tu configuración de paso de proxy. Suponiendo que estás usando Nginx, tu endpoint de autenticación de Logto está ejecutándose en el puerto 3001, y tu consola de administración de Logto está ejecutándose en el 3002, coloca la siguiente configuración en nginx.conf: +Si deseas usar un proxy inverso en tu servidor, por ejemplo Nginx o Apache, necesitas mapear los puertos 3001 y 3002 por separado en la configuración de tu proxy pass. Suponiendo que usas Nginx, tu endpoint de autenticación de Logto se ejecuta en el puerto 3001 y tu consola de administración de Logto en el 3002, coloca la siguiente configuración en nginx.conf: ``` server { listen 443 ssl; - server_name ; // ej. auth.your-domain.com + server_name ; // ej. auth.tu-dominio.com ... location / { @@ -52,8 +56,8 @@ server { proxy_pass http://127.0.0.1:3001; } - ssl_certificate ; - ssl_certificate_key + ssl_certificate ; + ssl_certificate_key ... } ``` @@ -63,7 +67,7 @@ Luego agrega una configuración similar para tu consola de administración: ``` server { listen 443 ssl; - server_name ; // ej. admin.your-domain.com + server_name ; // ej. admin.tu-dominio.com ... location / { @@ -75,8 +79,8 @@ server { proxy_pass http://127.0.0.1:3002; } - ssl_certificate ; - ssl_certificate_key + ssl_certificate ; + ssl_certificate_key ... } ``` @@ -87,17 +91,17 @@ Recarga la configuración de Nginx para aplicar los últimos cambios: nginx -s reload ``` -Todo está listo. Abre el navegador y visita `https://admin.your-domain.com`, deberías poder ver la página de bienvenida de Logto. +¡Todo listo! Abre el navegador y visita `https://admin.tu-dominio.com`, deberías poder ver la página de bienvenida de Logto. ## Contenerización \{#containerization} -Para producción, puedes usar Docker para contenerizar Logto. Puedes encontrar el Dockerfile en el directorio raíz del proyecto. Si deseas ejecutar múltiples instancias de Logto, por ejemplo, desplegar Logto en un clúster de Kubernetes, hay algunos pasos adicionales que necesitas seguir. +Para producción, puedes usar Docker para contenerizar Logto. Puedes encontrar el Dockerfile en el directorio raíz del proyecto. Si deseas ejecutar múltiples instancias de Logto, por ejemplo, desplegar Logto en un clúster de Kubernetes, hay algunos pasos adicionales que debes seguir. ### Carpeta de conectores compartida \{#shared-connectors-folder} -Por defecto, Logto creará una carpeta `connectors` en el directorio raíz de la carpeta `core`. Recomendamos compartir la carpeta entre múltiples instancias de Logto, necesitas montar la carpeta `packages/core/connectors` al contenedor y ejecutar `npm run cli connector add -- --official` para desplegar los conectores. +Por defecto, Logto creará una carpeta `connectors` en el directorio raíz de la carpeta `core`. Recomendamos compartir la carpeta entre múltiples instancias de Logto; necesitas montar la carpeta `packages/core/connectors` en el contenedor y ejecutar `npm run cli connector add -- --official` para desplegar los conectores. -Aquí tienes un ejemplo mínimo de `deployment` para Kubernetes: +Hay un ejemplo mínimo de `deployment` para Kubernetes: ```yaml apiVersion: extensions/v1beta1 @@ -130,21 +134,21 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -En este ejemplo, creamos un directorio vacío como un volumen y lo montamos en los contenedores. Luego ejecutamos `npm run cli connector add -- --official` en el contenedor de inicialización para descargar los conectores. Finalmente, cada contenedor compartirá la misma carpeta de conectores con nuestros conectores oficiales ya dentro. +En este ejemplo, creamos un directorio vacío como volumen y lo montamos en los contenedores. Luego ejecutamos `npm run cli connector add -- --official` en el contenedor de inicialización para descargar los conectores. Finalmente, cada contenedor compartirá la misma carpeta de conectores con nuestros conectores oficiales ya dentro. :::note -Este es un ejemplo de yaml, para ejecutar Logto, necesitas configurar las variables de entorno adecuadamente. +Este es un ejemplo de yaml, para ejecutar Logto necesitas establecer correctamente las variables de entorno. ::: -Para producción, puedes reemplazar el volumen de "directorio vacío" con un volumen persistente, y hacer el trabajo de "inicialización" a tu manera, ¡sabes lo que estás haciendo! +Para producción, puedes reemplazar el volumen "empty dir" por un volumen persistente y realizar el trabajo de "init" a tu manera, ¡tú sabes lo que haces! ### Alteración de la base de datos \{#database-alteration} -Similar a los conectores, la alteración de la base de datos necesita ejecutarse en una sola instancia. Puedes usar un trabajo para ejecutar el script de alteración. +Similar a los conectores, la alteración de la base de datos debe ejecutarse en una sola instancia. Puedes usar un job para ejecutar el script de alteración. -La variable de entorno `CI=true` es necesaria cuando la alteración se ejecuta de manera no interactiva. +La variable de entorno `CI=true` es necesaria cuando la alteración se ejecuta de forma no interactiva. ```yaml apiVersion: batch/v1 diff --git a/i18n/es/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..7aee7238dea --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# Bóveda de secretos + +La Bóveda de secretos en Logto está diseñada para almacenar de forma segura datos sensibles de los usuarios, como tokens de acceso (Access tokens), claves de API (API keys), códigos de acceso o cualquier otra información confidencial que requiera protección. Estos secretos suelen utilizarse para acceder a servicios de terceros en nombre del usuario, por lo que el almacenamiento seguro es esencial. + +## Esquema de cifrado \{#encryption-scheme} + +Para proteger los datos sensibles, la Bóveda de secretos emplea un esquema de cifrado robusto basado en **Claves de cifrado de datos (DEK)** y **Claves de cifrado de claves (KEK)**. + +- **Cifrado por secreto:** Cada secreto se cifra con su propia DEK única, lo que garantiza que, incluso si una clave se ve comprometida, los demás secretos permanecen seguros. +- **Envoltorio de claves:** La propia DEK se cifra (o "envuelve") con una KEK, que es gestionada y almacenada de forma segura por el sistema. +- **Seguridad en capas:** Este enfoque de dos niveles garantiza que, incluso si una parte del sistema se ve comprometida, los atacantes no puedan acceder a los secretos sin tanto la DEK como la KEK. +- **Exposición minimizada:** Los secretos solo se descifran cuando es absolutamente necesario, lo que reduce el riesgo de exposición accidental y se alinea con las mejores prácticas para el manejo de datos sensibles. + +Este modelo de cifrado en capas proporciona una protección sólida para las credenciales y tokens más sensibles de los usuarios, permitiendo al mismo tiempo el acceso seguro cuando sea necesario. + +## Tipos de secretos \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +Actualmente, el conjunto de tokens federados es el único tipo de secreto compatible de forma nativa. Sin embargo, la Bóveda de secretos está diseñada para adaptarse a cualquier tipo de información sensible. Si necesitas soporte para tipos de secretos adicionales, por favor [contáctanos](https://logto.io/contact) — estaremos encantados de ayudarte. +::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/es/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..3e4ec81d237 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: Conjunto de tokens federados (Federated token set) +sidebar_label: Conjunto de tokens federados (Federated token set) +--- + +import Availability from '@components/Availability'; + + + +El conjunto de tokens federados es un tipo de secreto almacenado en el Secret Vault de Logto, utilizado para gestionar de forma segura los tokens de acceso y actualización emitidos por proveedores de identidad de terceros federados. Cuando un usuario se autentica a través de un conector social o de SSO empresarial, Logto almacena los tokens emitidos en el vault. Estos tokens pueden recuperarse posteriormente para acceder a APIs de terceros en nombre del usuario, sin requerir una nueva autenticación. + +## Habilitar el almacenamiento de tokens federados \{#enable-federated-token-storage} + +### Conectores sociales \{#social-connectors} + +:::Info +Esta función solo está disponible para conectores que admiten almacenamiento de tokens. Los conectores actualmente soportados incluyen: [GitHub](/integrations/github), [Google](/integrations/google), [Facebook](/integrations/facebook), [OAuth 2.0 estándar](/integrations/oauth2) y [OIDC estándar](/integrations/oidc). El soporte para conectores adicionales se implementará gradualmente. +::: + +1. Navega a Consola > Conectores > Conectores sociales. +2. Selecciona el conector social para el que deseas habilitar el almacenamiento de tokens federados. +3. En la página "Configuración", habilita la opción **Almacenar tokens para acceso persistente a la API**. + +### Conectores de SSO empresarial \{#enterprise-sso-connectors} + +:::Info +El almacenamiento de tokens está disponible para todos los conectores empresariales OIDC. +::: + +1. Navega a Consola > SSO empresarial. +2. Selecciona el conector de SSO empresarial para el que deseas habilitar el almacenamiento de tokens federados. +3. En la pestaña "Experiencia SSO", habilita la opción **Almacenar tokens para acceso persistente a la API**. + +Asegúrate de guardar los cambios. + +## Almacenamiento de tokens \{#token-storage} + +Una vez habilitado el almacenamiento de tokens federados, Logto almacena automáticamente los tokens de acceso y actualización emitidos por el proveedor de identidad federado cada vez que un usuario se autentica a través de un conector social o de SSO empresarial. Esto incluye: + +- [Inicio de sesión y registro social](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [Inicio de sesión y registro con SSO empresarial](/end-user-flows/enterprise-sso) +- [Vinculación de cuentas sociales a través del Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +Los tokens almacenados se adjuntan a la identidad social o de SSO empresarial del usuario, permitiendo que los recupere posteriormente para acceder a APIs sin requerir una nueva autenticación. + +### Comprobar el estado del almacenamiento de tokens \{#checking-token-storage-status} + +Puedes comprobar el estado del almacenamiento de tokens federados de un usuario en la Consola de Logto: + +1. Navega a Consola > Usuarios. +2. Haz clic en el usuario que deseas inspeccionar. Esto te llevará a la página de detalles del usuario. +3. Desplázate hasta la sección **Conexiones**. Esta área muestra todas las conexiones sociales y de SSO empresarial asociadas al usuario. +4. Cada entrada de conexión muestra una etiqueta de estado de token que indica si los tokens están almacenados para esa conexión. +5. Haz clic en la entrada de la conexión para ver más detalles, incluyendo los metadatos del token de acceso almacenado y la disponibilidad del token de actualización (si está disponible). + +También puedes comprobar las identidades de terceros del usuario y el estado del almacenamiento de tokens a través del Management API: + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`: Recupera la identidad social de un usuario y el estado del almacenamiento de tokens asociado a la identidad por un conector específico (por ejemplo, `github`, `google`, etc.). +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`: Recupera la identidad de SSO empresarial de un usuario y el estado del almacenamiento de tokens asociado a la identidad por un ID de conector SSO dado. + +### Estado del almacenamiento de tokens \{#token-storage-status} + +- **Activo**: El token de acceso está almacenado y activo. +- **Expirado**: El token de acceso está almacenado pero ha expirado. Si hay un token de actualización disponible, puede usarse para obtener un nuevo token de acceso. +- **Inactivo**: No hay token de acceso almacenado para esta conexión. Esto puede ocurrir si el usuario no se ha autenticado a través de esta conexión o si el almacenamiento de tokens ha sido eliminado. +- **No aplicable**: El conector no admite almacenamiento de tokens. + +### Metadatos del token \{#token-metadata} + +Por integridad y seguridad de los datos, todos los tokens se cifran antes de almacenarse en el Secret Vault. Los valores reales de los tokens solo son accesibles para el usuario final con la autorización adecuada. Los desarrolladores, por otro lado, solo pueden recuperar los metadatos del conjunto de tokens para entender el estado de los tokens almacenados sin exponer contenido sensible. + +- `createdAt`: Marca de tiempo cuando se estableció la conexión por primera vez y el conjunto de tokens se almacenó inicialmente en el Secret Vault. +- `updatedAt`: La última vez que se actualizó el conjunto de tokens. + - Si no hay token de actualización disponible, este valor será igual a **createdAt**. + - Si hay un token de actualización presente, este valor refleja la última vez que se actualizó el token de acceso. +- `hasRefreshToken`: Indica si hay un token de actualización disponible. + Si el conector admite acceso offline y la solicitud de autorización está correctamente configurada, Logto almacena el token de actualización cuando es emitido por el proveedor de identidad junto con el token de acceso. + Cuando el token de acceso expira y existe un token de actualización válido, Logto intenta automáticamente obtener un nuevo token de acceso usando el token de actualización almacenado cada vez que el usuario solicita acceso al proveedor conectado. +- `expiresAt`: El tiempo estimado de expiración del token de acceso en **segundos**. + Esto se calcula en base al valor `expires_in` devuelto por el endpoint de tokens del proveedor de identidad. (Este campo solo está disponible si el proveedor incluye `expires_in` en la respuesta de tokens.) +- `scope`: El alcance (scope) del token de acceso, indicando los permisos otorgados por el proveedor de identidad. + Esto es útil para entender qué acciones pueden realizarse con el token de acceso almacenado. (Este campo solo está disponible si el proveedor incluye `scope` en la respuesta de tokens.) +- `tokenType`: El tipo de token de acceso, típicamente "Bearer". + (Este campo solo está disponible si el proveedor incluye `token_type` en la respuesta de tokens.) + +## Recuperación de tokens \{#token-retrieval} + +Una vez habilitado el almacenamiento de tokens y los tokens estén almacenados de forma segura en el Secret Vault de Logto, los usuarios finales pueden recuperar sus tokens de acceso de terceros desde tu aplicación cliente integrándose con el [Account API](/end-user-flows/account-settings/by-account-api) de Logto. + +- `GET /my-account/identities/:target/access-token`: Recupera el token de acceso para una identidad social especificando el conector (por ejemplo, github, google). + +- `GET /my-account/sso-identities/:connectorId/access-token`: Recupera el token de acceso para una identidad de SSO empresarial especificando el ID del conector. + +:::info +Aprende cómo [habilitar](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) y [acceder](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) al Account API usando el token de acceso emitido por Logto. +::: + +### Rotación de tokens \{#token-rotation} + +Los endpoints de recuperación de tokens devuelven: + +- `200` OK: Si el token de acceso se recupera correctamente y sigue siendo válido. +- `404` No encontrado: Si el usuario no tiene una identidad social o de SSO empresarial asociada con el target o ID de conector especificado, o si el token de acceso no está almacenado. +- `401` No autorizado: Si el token de acceso ha expirado. + +Si el token de acceso ha expirado y hay un token de actualización disponible, Logto intenta automáticamente refrescar el token de acceso y devuelve el nuevo token de acceso en la respuesta. El almacenamiento de tokens en el Secret Vault también se actualiza con el nuevo token de acceso y sus metadatos. + +## Eliminación del almacenamiento de tokens \{#token-storage-deletion} + +El almacenamiento de tokens federados está directamente vinculado a cada conexión social o de SSO empresarial del usuario. Esto significa que el conjunto de tokens almacenados se eliminará automáticamente en los siguientes casos: + +- Se elimina la identidad social o de SSO empresarial asociada de la cuenta del usuario. +- Se elimina la cuenta del usuario de tu tenant. +- Se elimina el conector social o de SSO empresarial de tu tenant. + +### Revocación de tokens \{#revoking-tokens} + +También puedes eliminar manualmente el conjunto de tokens de terceros de un usuario para revocar el acceso: + +- Desde la Consola: + Navega a la página de detalles de la identidad del usuario. Desplázate hasta la sección **Token de acceso** (si el almacenamiento de tokens está disponible) y haz clic en el botón **Eliminar tokens** al final de la sección. +- Vía Management API: + - `DELETE /api/secret/:id`: Elimina un secreto específico por su ID, que puede obtenerse desde los detalles de la identidad del usuario. + +Revocar el conjunto de tokens obligará al usuario a autenticarse nuevamente con el proveedor de terceros para obtener un nuevo token de acceso antes de poder acceder a las APIs de terceros nuevamente. + +## Reautenticación y renovación de tokens \{#reauthentication-and-token-renewal} + +En escenarios donde un token de acceso almacenado ha expirado o cuando una aplicación necesita solicitar alcances (scopes) adicionales de API, los usuarios finales pueden reautenticarse con el proveedor de terceros para obtener un nuevo token de acceso, sin necesidad de iniciar sesión en Logto nuevamente. +Esto puede lograrse a través del [Social Verification API](https://openapi.logto.io/operation/operation-createverificationbysocial) de Logto, que permite a los usuarios reiniciar un flujo de autorización social federada y actualizar su conjunto de tokens almacenados. + +:::note +La reiniciación de la autorización federada está actualmente limitada a conectores sociales. +Para conectores de SSO empresarial, la reautenticación y renovación de tokens requiere que el usuario inicie un flujo completo de autenticación de Logto nuevamente, ya que la reautorización directa con el proveedor de SSO empresarial no está soportada tras el inicio de sesión. +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as Usuario + participant Logto as Logto + participant Provider as Proveedor de terceros + + User->>Logto: post /api/verification/social + Logto->>User: Redirigir a proveedor de terceros + User->>Provider: Autenticar y autorizar + Provider->>User: Redirigir de vuelta con código de autorización + User->>Logto: post /api/verification/social/verify con código de autorización + Logto->>User: Devolver el ID de verificación social + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. El usuario inicia una solicitud de verificación social llamando al endpoint `POST /api/verification/social`. El usuario puede especificar scopes personalizados para solicitar permisos adicionales al proveedor de terceros. + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**: El token de acceso del usuario emitido por Logto. + - **connectorId**: El ID del conector social en Logto. + - **redirectUri**: La URI a la que redirigir al usuario de vuelta a tu aplicación después de la autenticación. Deberás registrar esta URI en la configuración de la aplicación del proveedor. + - **scope**: (Opcional) Scopes personalizados para solicitar permisos adicionales al proveedor de terceros. Si no se especifica, se usarán los scopes predeterminados configurados en el conector. + +2. Logto crea un nuevo registro de verificación social y devuelve el ID de verificación social junto con la URL de autorización para redirigir al usuario al proveedor de terceros para autenticación. + + La respuesta tendrá el siguiente aspecto: + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. Redirige al usuario a la URL de autorización. El usuario se autentica con el proveedor de terceros y otorga permisos. + +4. El proveedor de terceros redirige al usuario de vuelta a tu aplicación cliente con un código de autorización. + +5. Maneja el callback de autorización reenviando el código de autorización al endpoint de verificación de Logto: + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**: El token de acceso del usuario emitido por Logto. + - **verificationRecordId**: El ID de verificación social devuelto en el paso anterior. + - **connectorData**: El código de autorización y cualquier otro dato devuelto por el proveedor de terceros durante el callback. + + :::note + No olvides validar el parámetro `state` para prevenir ataques CSRF. + ::: + +6. Logto verifica el código de autorización y lo intercambia por un nuevo token de acceso y token de actualización del proveedor de terceros, luego devuelve el ID de verificación social en la respuesta. + +7. Finalmente, actualiza el almacenamiento de tokens del usuario llamando al endpoint `PATCH /my-account/identities/:target/access-token` con el ID de verificación social: + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**: El token de acceso del usuario emitido por Logto. + - **socialVerificationId**: El ID de registro de verificación social verificado devuelto en el paso anterior. + + Esto actualizará el almacenamiento del conjunto de tokens del usuario en el Secret Vault de Logto con el nuevo token de acceso y token de actualización, permitiendo al usuario acceder a APIs de terceros sin necesidad de iniciar sesión en Logto nuevamente. + + El token de acceso actualizado será devuelto. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/es/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 7eddd922c1b..55f85c4e1d6 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -2,9 +2,9 @@ sidebar_position: 4 --- -# Token de acceso personal (Personal access token) +# Token de acceso personal -Los tokens de acceso personal (PATs) proporcionan una forma segura para que los usuarios otorguen [token de acceso (Access token)](https://auth.wiki/access-token) sin usar sus credenciales ni el inicio de sesión interactivo. Esto es útil para CI/CD, scripts o aplicaciones que necesitan acceder a recursos de forma programática. +Los tokens de acceso personal (PATs) proporcionan una forma segura para que los usuarios otorguen un [token de acceso (Access token)](https://auth.wiki/access-token) sin usar sus credenciales ni el inicio de sesión interactivo. Esto es útil para CI / CD, scripts o aplicaciones que necesitan acceder a recursos de forma programática. ## Gestión de tokens de acceso personal \{#managing-personal-access-tokens} @@ -20,14 +20,26 @@ Después de configurar la [Management API](/integrate-logto/interact-with-manage Después de crear un PAT, puedes usarlo para otorgar tokens de acceso a tu aplicación utilizando el endpoint de intercambio de tokens. +:::tip Equivalencia del flujo de tokens + +Los tokens de acceso obtenidos usando PATs funcionan **idénticamente** a los tokens obtenidos a través del flujo estándar de `refresh_token`. Esto significa: + +- **Contexto de organización**: Los tokens obtenidos por PAT admiten los mismos permisos y alcances de organización que los flujos de refresh token +- **Flujo de autorización**: Puedes usar los tokens de acceso intercambiados por PAT para [permisos de organización](/authorization/organization-permissions) y [recursos de API a nivel de organización](/authorization/organization-level-api-resources) +- **Validación de tokens**: Se aplica la misma lógica de validación: solo difiere el tipo de concesión inicial + +Si trabajas con organizaciones, los patrones de acceso y permisos son los mismos independientemente de si usas PAT o tokens de actualización (refresh tokens). + +::: + ### Solicitud \{#request} La aplicación realiza una [solicitud de intercambio de tokens](https://auth.wiki/authorization-code-flow#token-exchange-request) al [endpoint de token](/integrate-logto/application-data-structure#token-endpoint) del tenant con un tipo de concesión especial usando el método HTTP POST. Los siguientes parámetros se incluyen en el cuerpo de la solicitud HTTP usando el formato `application/x-www-form-urlencoded`. 1. `client_id`: OBLIGATORIO. El ID de cliente de la aplicación. 2. `grant_type`: OBLIGATORIO. El valor de este parámetro debe ser `urn:ietf:params:oauth:grant-type:token-exchange` e indica que se está realizando un intercambio de tokens. -3. `resource`: OPCIONAL. El indicador de recurso (resource indicator), igual que en otras solicitudes de token. -4. `scope`: OPCIONAL. Los alcances (scopes) solicitados, igual que en otras solicitudes de token. +3. `resource`: OPCIONAL. El indicador de recurso, igual que en otras solicitudes de token. +4. `scope`: OPCIONAL. Los alcances solicitados, igual que en otras solicitudes de token. 5. `subject_token`: OBLIGATORIO. El PAT del usuario. 6. `subject_token_type`: OBLIGATORIO. El tipo de token de seguridad proporcionado en el parámetro `subject_token`. El valor de este parámetro debe ser `urn:logto:token-type:personal_access_token`. @@ -39,9 +51,9 @@ Si la solicitud de intercambio de tokens es exitosa, el endpoint de token del te 2. `issued_token_type`: OBLIGATORIO. El tipo de token emitido. El valor de este parámetro debe ser `urn:ietf:params:oauth:token-type:access_token`. 3. `token_type`: OBLIGATORIO. El tipo de token. El valor de este parámetro debe ser `Bearer`. 4. `expires_in`: OBLIGATORIO. El tiempo de vida en segundos del token de acceso. -5. `scope`: OPCIONAL. Los alcances (scopes) del token de acceso. +5. `scope`: OPCIONAL. Los alcances del token de acceso. -### Ejemplo de intercambio de token \{#example-token-exchange} +### Ejemplo de intercambio de tokens \{#example-token-exchange} ``` POST /oidc/token HTTP/1.1 @@ -89,6 +101,6 @@ El payload de ejemplo del token de acceso: - Tokens de acceso personal, autenticación máquina a máquina (Machine-to-Machine), y definición de - API Keys y sus escenarios en el mundo real + Tokens de acceso personal, autenticación máquina a máquina y definición de API Keys y sus + escenarios en el mundo real diff --git a/i18n/es/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/es/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index bcfad7afc3a..9e85968f80e 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -4,23 +4,25 @@ sidebar_position: 5 # Migración de usuarios -Logto admite la migración manual de usuarios existentes desde otra plataforma. Esta guía te mostrará cómo importar usuarios existentes a través de la Management API (Management API) y hablará sobre aspectos que debes considerar antes de migrar. +Logto admite la migración manual de usuarios existentes desde otra plataforma. Esta guía te mostrará cómo importar usuarios existentes a través de la Management API y hablará sobre aspectos que debes considerar antes de migrar. ## Esquema de usuario \{#user-schema} Antes de comenzar, echemos un vistazo al [esquema de usuario](/user-management/user-data/#user-profile) en Logto. Hay 3 partes del esquema de usuario que debes conocer: -1. **Datos básicos**: es la información básica del perfil del usuario, puedes hacer coincidir los datos desde tu perfil de usuario existente. +1. **Datos básicos**: es la información básica del perfil de usuario, puedes hacer coincidir los datos desde tu perfil de usuario existente. 2. **Datos personalizados**: almacena información adicional del usuario, puedes usar esto para guardar archivos que no puedan coincidir con los datos básicos. 3. **Identidades sociales**: almacena la información del usuario obtenida del inicio de sesión social. -Puedes crear un mapeo para hacer coincidir la información del usuario de tu perfil existente con los **datos básicos** y **datos personalizados**. Para el inicio de sesión social, necesitarás pasos adicionales para importar las identidades sociales; consulta la API de [Vincular identidad social al usuario](https://openapi.logto.io/operation/operation-createuseridentity). +Puedes crear un mapa para hacer coincidir la información del usuario de tu perfil existente con los **datos básicos** y **datos personalizados**. Para el inicio de sesión social, necesitarás pasos adicionales para importar las identidades sociales; consulta la API de [Vincular identidad social a usuario](https://openapi.logto.io/operation/operation-createuseridentity). ## Hashing de contraseñas \{#password-hashing} -Logto utiliza [Argon2](https://en.wikipedia.org/wiki/Argon2) para hashear la contraseña del usuario, y también admite otros algoritmos como `MD5`, `SHA1`, `SHA256` y `Bcrypt` para facilitar la migración. Esos algoritmos se consideran inseguros; los hashes de contraseña correspondientes se migrarán a Argon2 en el primer inicio de sesión exitoso del usuario. +Logto utiliza [Argon2](https://es.wikipedia.org/wiki/Argon2) para hashear la contraseña del usuario, y también admite otros algoritmos como `MD5`, `SHA1`, `SHA256` y `Bcrypt` para facilitar la migración. Esos algoritmos se consideran inseguros; los hashes de contraseña correspondientes se migrarán a Argon2 en el primer inicio de sesión exitoso del usuario. -Si estás utilizando otros algoritmos de hash o salt, puedes establecer `passwordAlgorithm` en `Legacy`. Esto te permite usar cualquier algoritmo de hash soportado por Node.js. Puedes encontrar la lista de algoritmos soportados en la [documentación de Node.js crypto](https://nodejs.org/api/crypto.html#cryptogethashes). En este caso, el `passwordDigest` será una cadena JSON que contiene el algoritmo de hash y otros parámetros específicos del algoritmo. +Si estás utilizando otros algoritmos de hash o salt, puedes establecer `passwordAlgorithm` en `Legacy`, lo que te permite usar cualquier algoritmo de hash compatible con Node.js. Puedes encontrar la lista de algoritmos compatibles en la [documentación de Node.js crypto](https://nodejs.org/api/crypto.html#cryptogethashes). En este caso, el `passwordDigest` será una cadena JSON que contiene el algoritmo de hash y otros parámetros específicos del algoritmo. + +### Formato general Legacy \{#general-legacy-format} El formato de la cadena JSON es el siguiente: @@ -44,10 +46,40 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### Soporte para PBKDF2 \{#pbkdf2-support} + +Logto admite específicamente [PBKDF2](https://es.wikipedia.org/wiki/PBKDF2). + +Para migrar contraseñas hasheadas con PBKDF2, establece `passwordAlgorithm` en `Legacy` y formatea el `passwordDigest` de la siguiente manera: + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +Los parámetros son: + +- **`salt`**: El valor de salt utilizado en el hash original +- **`iterations`**: Número de iteraciones (por ejemplo, `"1000"`) +- **`keylen`**: Longitud de la clave derivada en bytes (por ejemplo, `"20"`) +- **`digest`**: La función hash utilizada (por ejemplo, `"sha512"`, `"sha256"`, `"sha1"`) +- **`@`**: Marcador de posición para el valor real de la contraseña +- **`expected_hashed_value`**: El resultado esperado del hash como una cadena hexadecimal + +**Ejemplo de payload de migración:** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## Pasos para migrar \{#steps-to-migrate} -1. **Preparar los datos de usuario** - Primero debes exportar los datos de usuario de tu plataforma existente y luego mapear la información del usuario al esquema de usuario de Logto. Te recomendamos preparar los datos mapeados en formato JSON. Aquí tienes un ejemplo de los datos de usuario: +1. **Prepara los datos de usuario** + Primero debes exportar los datos de usuario desde tu plataforma existente y luego mapear la información del usuario al esquema de usuario de Logto. Te recomendamos preparar los datos mapeados en formato JSON. Aquí tienes un ejemplo de los datos de usuario: ```json [ @@ -64,11 +96,11 @@ const expectedHashedValue = hash.digest('hex'); ] ``` -2. **Crear un tenant de Logto** +2. **Crea un tenant en Logto** Necesitarás configurar un tenant en Logto. Puedes usar Logto Cloud o Logto OSS. Si aún no lo has hecho, consulta la guía [Configurar Logto cloud](/introduction/set-up-logto-cloud/#create-logto-tenant). -3. **Configurar la conexión de la Management API** - Usaremos la Management API (Management API) para importar los datos de usuario. Puedes consultar la [Management API](/integrate-logto/interact-with-management-api) para aprender cómo configurar la conexión en tu entorno de desarrollo. -4. **Importar los datos de usuario** +3. **Configura la conexión con la Management API** + Usaremos la Management API para importar los datos de usuario. Puedes consultar la [Management API](/integrate-logto/interact-with-management-api) para aprender cómo configurar la conexión en tu entorno de desarrollo. +4. **Importa los datos de usuario** Se recomienda preparar un script para importar los datos de usuario uno por uno. Llamaremos a la API de [crear usuario](https://openapi.logto.io/operation/operation-createuser) para importar los datos de usuario. Aquí tienes un ejemplo de script: ```jsx @@ -85,10 +117,10 @@ const expectedHashedValue = hash.digest('hex'); }, body: JSON.stringify(user), }); - // Dormir un momento para evitar el límite de tasa + // Sleep for a while to avoid rate limit await new Promise((resolve) => setTimeout(resolve, 200)); } catch (error) { - console.error(`No se pudo importar el usuario ${user.username}: ${error.message}`); + console.error(`Failed to import user ${user.username}: ${error.message}`); } } }; @@ -96,9 +128,9 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -Ten en cuenta que el endpoint de la API tiene límite de tasa; debes añadir una pausa entre cada solicitud para evitar el límite. Consulta nuestra página de [límites de tasa](/integrate-logto/interact-with-management-api/#rate-limit) para más detalles. +Ten en cuenta que el endpoint de la API tiene límite de velocidad; debes agregar una pausa entre cada solicitud para evitar el límite. Consulta nuestra página de [límites de velocidad](/integrate-logto/interact-with-management-api/#rate-limit) para más detalles. -Si tienes una gran cantidad de datos de usuario (más de 100k usuarios), puedes [contactarnos](https://logto.io/contact) para aumentar el límite de tasa. +Si tienes una gran cantidad de datos de usuario (más de 100k usuarios), puedes [contactarnos](https://logto.io/contact) para aumentar el límite de velocidad. ## Recursos relacionados \{#related-resources} diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/fr/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index 69b85e6a43e..2b012720b68 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -1,4 +1,4 @@ -# Configuration +# Configuration (Configuration) ## Variables d'environnement {#environment-variables} @@ -19,46 +19,47 @@ Si vous exécutez Logto via `npm start` à la racine du projet, `NODE_ENV` sera Dans les valeurs par défaut, `protocol` sera soit `http` soit `https` selon votre configuration HTTPS. -| Key | Valeur par défaut | Type | Description | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Quel type d'environnement dans lequel Logto fonctionne. | -| PORT | `3001` | `number` | Le port local auquel Logto écoute. | -| ADMIN_PORT | `3002` | `number` | Le port local auquel la console d'administration de Logto écoute. | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Définissez-le sur `1` ou `true` pour désactiver le port pour la console d'administration. Avec `ADMIN_ENDPOINT` non défini, cela désactivera complètement la console d'administration. | -| DB_URL | N/A | `string` | Le [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) pour la base de données Logto. | -| HTTPS_CERT_PATH | `undefined` | string | undefined | Voir [Activation de HTTPS](#enabling-https) pour plus de détails. | -| HTTPS_KEY_PATH | `undefined` | string | undefined | Idem. | -| TRUST_PROXY_HEADER | `false` | `boolean` | Idem. | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Vous pouvez spécifier une URL avec votre domaine personnalisé pour les tests en ligne ou la production. Cela affectera également la valeur de l' identifiant de l' Émetteur (OIDC) . | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (par exemple `ADMIN_ENDPOINT=https://admin.domain.com`). Cela affectera également la valeur des URI de redirection de la console d'administration. | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Spécifie si le nom d'utilisateur est sensible à la casse. Faites preuve de prudence lors de la modification de cette valeur ; les modifications n'ajusteront pas automatiquement les données existantes de la base de données, nécessitant une gestion manuelle. | +| Clé | Valeur par défaut | Type | Description | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Le type d'environnement dans lequel Logto s'exécute. | +| PORT | `3001` | `number` | Le port local sur lequel Logto écoute. | +| ADMIN_PORT | `3002` | `number` | Le port local sur lequel la Console d'administration Logto écoute. | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Définissez-le à `1` ou `true` pour désactiver le port pour la Console d'administration. Si `ADMIN_ENDPOINT` n'est pas défini, cela désactivera complètement la Console d'administration. | +| DB_URL | N/A | `string` | Le [DSN Postgres](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) pour la base de données Logto. | +| HTTPS_CERT_PATH | `undefined` | string | undefined | Voir [Activation de HTTPS](#enabling-https) pour plus de détails. | +| HTTPS_KEY_PATH | `undefined` | string | undefined | Idem. | +| TRUST_PROXY_HEADER | `false` | `boolean` | Idem. | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Vous pouvez spécifier une URL avec votre domaine personnalisé pour les tests en ligne ou la production. Cela affectera également la valeur de l'[identifiant d’émetteur OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (ex : `ADMIN_ENDPOINT=https://admin.domain.com`). Cela affectera également la valeur des URI de redirection de la Console d'administration. | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Spécifie si le nom d'utilisateur est sensible à la casse. Faites attention lors de la modification de cette valeur ; les changements n'ajusteront pas automatiquement les données existantes de la base de données, nécessitant une gestion manuelle. | +| SECRET_VAULT_KEK | `undefined` | `string` | La clé de chiffrement principale (KEK) utilisée pour chiffrer les clés de chiffrement des données (DEK) dans le [Secret Vault](/secret-vault). Requise pour le bon fonctionnement du Secret Vault. Doit être une chaîne encodée en base64. AES-256 (32 octets) est recommandé. Exemple : `crypto.randomBytes(32).toString('base64')` | ### Activation de HTTPS {#enabling-https} #### Utilisation de Node {#using-node} -Node prend en charge nativement HTTPS. Fournissez **BOTH** `HTTPS_CERT_PATH` et `HTTPS_KEY_PATH` pour activer HTTPS via Node. +Node prend en charge HTTPS nativement. Fournissez **LES DEUX** `HTTPS_CERT_PATH` et `HTTPS_KEY_PATH` pour activer HTTPS via Node. -`HTTPS_CERT_PATH` implique le chemin vers votre certificat HTTPS, tandis que `HTTPS_KEY_PATH` implique le chemin vers votre clé HTTPS. +`HTTPS_CERT_PATH` indique le chemin vers votre certificat HTTPS, tandis que `HTTPS_KEY_PATH` indique le chemin vers votre clé HTTPS. #### Utilisation d'un proxy HTTPS {#using-a-https-proxy} -Une autre pratique courante consiste à avoir un proxy HTTPS devant Node (par exemple Nginx). +Une autre pratique courante consiste à placer un proxy HTTPS devant Node (ex : Nginx). -Dans ce cas, vous voudrez probablement définir `TRUST_PROXY_HEADER` sur `true`, ce qui indique si les champs d'en-tête de proxy doivent être approuvés. Logto passera la valeur aux paramètres de l'application [Koa](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). +Dans ce cas, vous souhaiterez probablement définir `TRUST_PROXY_HEADER` à `true`, ce qui indique si les champs d'en-tête du proxy doivent être approuvés. Logto transmettra la valeur aux [paramètres de l'application Koa](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). Voir [Trusting TLS offloading proxies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) pour savoir quand configurer ce champ. -## Configurations de la base de données {#database-configs} +## Configurations de base de données {#database-configs} -Gérer trop de variables d'environnement n'est pas efficace et flexible, donc la plupart de nos configurations générales sont stockées dans la table de base de données `logto_configs`. +Gérer trop de variables d'environnement n'est ni efficace ni flexible, c'est pourquoi la plupart de nos configurations générales sont stockées dans la table de base de données `logto_configs`. La table est un simple stockage clé-valeur, et la clé est énumérable comme suit : -| Key | Type | Description | -| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| oidc.cookieKeys | string[] | Le tableau de chaînes des [clés de signature de cookie](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | -| oidc.privateKeys | string[] | Le tableau de chaînes du contenu de la clé privée pour la signature de Jeton d’identifiant (OIDC) . | +| Clé | Type | Description | +| ---------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| oidc.cookieKeys | string[] | Le tableau de chaînes des [clés de signature de cookie](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | +| oidc.privateKeys | string[] | Le tableau de chaînes du contenu de la clé privée pour la [signature JWT OIDC](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | ### Types de clés privées pris en charge {#supported-private-key-types} diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index 7673638d5e8..d002f28b01f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -90,7 +90,7 @@ Si nos connecteurs standards ne répondent pas à vos besoins spécifiques, n’ 3. Fournissez un nom unique (par exemple, Okta pour Acme Company). 4. Configurez la connexion avec votre IdP dans l’onglet "Connexion". Consultez les guides ci-dessus pour chaque type de connecteur. 5. Personnalisez l’expérience SSO et le **domaine e-mail** dans l’onglet "Expérience". -6. Pour le connecteur SAML d’entreprise, l’activation du SSO initié par l’IdP dans l’onglet "SSO initié par l’IdP" est facultative. [Consultez le guide](/end-user-flows/enterprise-sso/idp-initiated-sso) pour plus de détails. +6. Pour le connecteur SAML d’entreprise, l’activation du SSO initié par l’IdP dans l’onglet "SSO initié par l’IdP" est optionnelle. [Consultez le guide](/end-user-flows/enterprise-sso/idp-initiated-sso) pour plus de détails. 7. Enregistrez les modifications. Veuillez noter les paramètres suivants : @@ -100,11 +100,12 @@ Veuillez noter les paramètres suivants : :::note Il est important de noter qu’après avoir configuré les domaines e-mail concernés dans un connecteur SSO, les utilisateurs se connectant avec des e-mails appartenant à ces domaines seront obligés d’utiliser la [connexion SSO](/end-user-flows/enterprise-sso). - En d’autres termes, seuls les e-mails provenant de domaines qui ne sont PAS configurés dans les connecteurs SSO peuvent utiliser la connexion "e-mail + code de vérification" ou "e-mail + mot de passe" (à condition que ces deux méthodes de connexion soient activées dans l’expérience de connexion). + En d’autres termes, seuls les e-mails provenant de domaines qui NE sont PAS configurés dans les connecteurs SSO peuvent utiliser la connexion "e-mail + code de vérification" ou "e-mail + mot de passe" (à condition que ces deux méthodes de connexion soient activées dans l’expérience de connexion). ::: - **Synchronisation des profils utilisateur** : Choisissez quand synchroniser les informations du profil utilisateur (par exemple, avatar, nom). Le comportement par défaut est "Synchroniser uniquement lors de la première connexion". "Toujours synchroniser à chaque connexion" est une autre option pour ce champ, mais cela peut entraîner l’écrasement des données utilisateur personnalisées. -- **Informations d’affichage** : Vous pouvez personnaliser le nom d’affichage et le logo du connecteur. Ceci est très utile lorsque plusieurs connecteurs sont associés au même domaine e-mail. Les utilisateurs sélectionneront le fournisseur d’identité (IdP) souhaité dans une liste de boutons de connecteurs SSO avant d’être redirigés vers la page de connexion de l’IdP. +- **Activer le stockage des jetons** : Pour les connecteurs OIDC d’entreprise, vous pouvez activer le stockage des jetons pour enregistrer en toute sécurité les jetons d’accès (Jetons d’accès) et de rafraîchissement (Jetons de rafraîchissement) dans le [Coffre-fort des secrets](/secret-vault) de Logto lorsque les utilisateurs se connectent avec un IdP d’entreprise. Cela permet à votre application d’accéder à des API tierces au nom de l’utilisateur sans lui demander de se réauthentifier. En savoir plus sur le [stockage fédéré des jetons](/secret-vault/federated-token-set). +- **Informations d’affichage** : Personnalisez éventuellement le nom d’affichage et le logo du connecteur. Ceci est très utile lorsque plusieurs connecteurs sont associés au même domaine e-mail. Les utilisateurs sélectionneront le fournisseur d’identité (IdP) souhaité dans une liste de boutons de connecteurs SSO avant d’être redirigés vers la page de connexion de l’IdP. ## Activation du SSO d’entreprise \{#enabling-enterprise-sso} @@ -116,9 +117,9 @@ Une fois activé, un bouton "Authentification unique (SSO)" apparaîtra sur votr ## Just-in-time vers une organisation \{#just-in-time-to-organization} -Dans Logto, [l’approvisionnement Just-in-Time (JIT)](https://auth.wiki/jit-provisioning) est un processus utilisé pour attribuer automatiquement des appartenances à des organisations et des rôles aux utilisateurs lors de leur première connexion au système. +Dans Logto, [l’approvisionnement Just-in-Time (JIT)](https://auth.wiki/jit-provisioning) est un processus utilisé pour attribuer automatiquement des appartenances à des organisations et des rôles aux utilisateurs à la volée lors de leur première connexion au système. -Logto propose un point d’entrée pour configurer l’approvisionnement JIT des connecteurs SSO au sein d’une organisation, voir [référence](/organizations/just-in-time-provisioning). +Logto propose un point d’entrée pour configurer l’approvisionnement JIT du connecteur SSO au sein d’une organisation, voir [référence](/organizations/just-in-time-provisioning). ## FAQ \{#faqs} @@ -130,7 +131,7 @@ Logto propose un point d’entrée pour configurer l’approvisionnement JIT des - Ajout du SSO : Les identités SSO seront liées aux comptes existants si l’e-mail correspond. -- Suppression du SSO : Supprime les identités SSO liées au compte, mais conserve les comptes utilisateurs et invite les utilisateurs à configurer des méthodes de vérification alternatives. +- Suppression du SSO : Supprime les identités SSO liées au compte, mais conserve les comptes utilisateurs et invite les utilisateurs à configurer d’autres méthodes de vérification. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/connectors/social.mdx index f3b960b0a96..8b165bc2169 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,7 +7,7 @@ sidebar_position: 3 # Connecteurs sociaux -Simplifiez l'intégration des utilisateurs et augmentez les taux de conversion en activant la [connexion sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in) avec Logto. Les utilisateurs peuvent se connecter rapidement et en toute sécurité en utilisant leurs comptes de réseaux sociaux existants, éliminant ainsi le besoin de créer un mot de passe ou de suivre un processus d'inscription complexe. Logto propose une variété de connecteurs sociaux préconstruits et prend en charge les intégrations personnalisées pour une flexibilité maximale. +Simplifiez l'intégration des utilisateurs et augmentez les taux de conversion en activant la [connexion sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in) avec Logto. Les utilisateurs peuvent se connecter rapidement et en toute sécurité en utilisant leurs comptes de réseaux sociaux existants, éliminant ainsi la nécessité de créer un mot de passe ou de suivre un processus d'inscription complexe. Logto propose une variété de connecteurs sociaux préconfigurés et prend en charge les intégrations personnalisées pour une flexibilité maximale. ## Choisissez vos connecteurs sociaux \{#choose-your-social-connectors} @@ -15,7 +15,7 @@ Logto propose deux types de connecteurs sociaux : ### Connecteurs sociaux populaires \{#popular-social-connectors} -Logto fournit des connecteurs préconfigurés pour les plateformes sociales populaires, prêts à être utilisés immédiatement. +Logto fournit des connecteurs préconfigurés pour les plateformes sociales populaires, prêts à l'emploi. ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -88,7 +88,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -[Et plus](/integrations)... +[Et plus encore](/integrations)... ### Personnalisez vos connecteurs sociaux \{#customize-your-social-connectors} @@ -119,29 +119,30 @@ Pour des besoins personnalisés, utilisez les standards OAuth 2.0 et OIDC (OpenI /> ``` -Si nos connecteurs standard ne répondent pas à vos besoins spécifiques, n'hésitez pas à [nous contacter](https://logto.productlane.com/roadmap). Pour les utilisateurs OSS, vous pouvez [implémenter votre connecteur (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) si le besoin est urgent. Nous accueillons toujours les [contributions](/logto-oss/contribution) ; votre effort pourrait bien aider d'autres membres de la communauté ayant les mêmes besoins. +Si nos connecteurs standards ne répondent pas à vos besoins spécifiques, n'hésitez pas à [nous contacter](https://logto.productlane.com/roadmap). Pour les utilisateurs OSS, vous pouvez [implémenter votre connecteur (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) si le besoin est urgent. Nous accueillons toujours les [contributions](/logto-oss/contribution) ; votre effort pourrait bien aider d'autres membres de la communauté ayant les mêmes besoins. ## Étapes de configuration \{#configuration-steps} 1. Accédez à Console > Connecteurs > Connecteurs sociaux. 2. Cliquez sur "Ajouter un connecteur social" et sélectionnez le type souhaité. -3. Suivez le guide README et complétez les champs requis et personnalisez les paramètres. -4. Cliquez sur "Enregistrer et Terminer" pour terminer. +3. Suivez le guide README, complétez les champs requis et personnalisez les paramètres. +4. Cliquez sur "Enregistrer et terminer" pour finaliser. 5. Testez le connecteur en initiant une connexion sociale. Veuillez noter les paramètres suivants : -- **Nom du fournisseur d'identité** : Chaque connecteur social a un nom unique de fournisseur d'identité (IdP) pour différencier les identités des utilisateurs. Alors que les connecteurs courants utilisent un nom IdP fixe, les connecteurs personnalisés nécessitent une valeur unique. En savoir plus sur les [noms IdP](/connectors/connector-data-structure#target-identity-provider-name) pour plus de détails. -- **Synchroniser les profils utilisateurs** : Choisissez quand synchroniser les [informations de profil utilisateur](/user-management/user-data#social-identities) (par exemple, avatar, nom d'utilisateur). Par défaut, la synchronisation se fait "uniquement lors de l'inscription". "Synchroniser à chaque connexion" est une alternative mais peut écraser les données utilisateur personnalisées. +- **Nom du fournisseur d'identité** : Chaque connecteur social possède un nom unique de fournisseur d'identité (IdP) pour différencier les identités utilisateur. Alors que les connecteurs courants utilisent un nom IdP fixe, les connecteurs personnalisés nécessitent une valeur unique. En savoir plus sur les [noms IdP](/connectors/connector-data-structure#target-identity-provider-name) pour plus de détails. +- **Synchroniser les profils utilisateur** : Choisissez quand synchroniser les [informations du profil utilisateur](/user-management/user-data#social-identities) (par exemple, avatar, nom d'utilisateur). Par défaut, la synchronisation se fait "uniquement lors de l'inscription". "Synchroniser à chaque connexion" est une alternative mais peut écraser les données utilisateur personnalisées. +- **Activer le stockage des jetons** : Pour les connecteurs sociaux compatibles, vous pouvez activer le stockage des jetons pour enregistrer en toute sécurité les jetons d’accès et de rafraîchissement dans le [Secret Vault](/secret-vault) de Logto lorsque les utilisateurs se connectent avec un fournisseur social. Cela permet à votre application d'accéder aux API tierces au nom de l'utilisateur sans qu'il ait à se réauthentifier. En savoir plus sur le [stockage fédéré des jetons](/secret-vault/federated-token-set). ## Activer la connexion sociale \{#enable-social-sign-in} -Une fois que vous avez créé un connecteur social avec succès, vous pouvez l'activer en tant que bouton de connexion sociale (par exemple, Continuer avec Google) dans l'Expérience de connexion. +Une fois que vous avez créé un connecteur social avec succès, vous pouvez l'activer comme bouton de connexion sociale (par exemple, Continuer avec Google) dans l’Expérience de connexion. 1. Accédez à Console > Expérience de connexion > Inscription et connexion. -2. (Optionnel) Choisissez "Non applicable" pour l'identifiant d'inscription si vous avez uniquement besoin de la connexion sociale. +2. (Optionnel) Choisissez "Non applicable" pour l'identifiant d'inscription si vous souhaitez uniquement la connexion sociale. 3. Ajoutez les connecteurs sociaux configurés à la section "Connexion sociale". -4. Réorganisez les connecteurs si nécessaire. -5. Cliquez sur "Enregistrer les modifications" et testez l'"Aperçu en direct". +4. Réorganisez les connecteurs selon vos besoins. +5. Cliquez sur "Enregistrer les modifications" et testez l’"Aperçu en direct". Consultez [Connexion sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in) pour en savoir plus sur les détails. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index c9a7342b442..0c570cabba9 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -2,8 +2,8 @@ slug: /integrations/facebook sidebar_label: Facebook sidebar_custom_props: - description: Facebook est une plateforme de médias sociaux mondiale avec des milliards d'utilisateurs. -tutorial_config_name: Connexion Facebook + description: Facebook est une plateforme de médias sociaux mondiale comptant des milliards d'utilisateurs. +tutorial_config_name: Facebook login --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -12,18 +12,63 @@ import Integration from './_integration.mdx'; # Configurer la connexion sociale avec Facebook -Le connecteur officiel Logto pour la connexion sociale Facebook. +Intégrez le système d'authentification OAuth 2.0 de Facebook pour activer la connexion avec Facebook, la liaison de comptes et l'accès sécurisé aux API Facebook. ## Commencer \{#get-started} -Le connecteur Facebook offre un moyen concis pour votre application d'utiliser le système d'authentification OAuth 2.0 de Facebook. +Le connecteur Facebook permet l'intégration OAuth 2.0 pour permettre à votre application de : + +- Ajouter l'authentification “Connexion avec Facebook” +- Lier les comptes utilisateurs aux identités Facebook +- Synchroniser les informations de profil utilisateur depuis Facebook +- Accéder aux API Facebook via le stockage sécurisé des jetons dans le Secret Vault de Logto pour des tâches d'automatisation (par exemple, répondre à un fil de discussion ; publier du contenu et des vidéos dans votre application) + +Pour configurer ces fonctionnalités d'authentification, créez d'abord un connecteur Facebook dans Logto : + +1. Accédez à [Logto > Connecteur > Connecteur social](https://cloud.logto.io/to/connectors/social). +2. Cliquez sur **Ajouter un connecteur social**, sélectionnez **Facebook**, cliquez sur **Suivant** et suivez le tutoriel étape par étape pour finaliser l'intégration. -## Références \{#references} +## Utiliser le connecteur Facebook \{#utilize-the-facebook-connector} + +Une fois que vous avez créé un connecteur Facebook et que vous l'avez connecté à Facebook, vous pouvez l'intégrer dans vos parcours utilisateurs. Choisissez les options qui correspondent à vos besoins : + +### Activer “Connexion avec Facebook” \{#enable-sign-in-with-facebook} + +1. Dans la Console Logto, allez dans Expérience de connexion > Inscription et connexion +2. Ajoutez le connecteur Facebook dans la section **Connexion sociale** pour permettre aux utilisateurs de s'authentifier avec Facebook + +En savoir plus sur [l'expérience de connexion sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Lier ou délier un compte Facebook \{#link-or-unlink-a-facebook-account} + +Utilisez l'Account API pour construire un Centre de compte personnalisé dans votre application permettant aux utilisateurs connectés de lier ou délier leur compte Facebook. [Suivez le tutoriel Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Il est possible d'activer le connecteur Facebook uniquement pour la liaison de compte et l'accès à l'API, sans l'activer pour la connexion sociale. +::: + +### Accéder à l'API Facebook et effectuer des actions \{#access-facebook-api-and-perform-actions} + +Votre application peut récupérer les jetons d’accès Facebook stockés dans le Secret Vault pour appeler les API Facebook et automatiser des tâches backend (par exemple, publier du contenu ou gérer des publications). Consultez le guide sur la récupération des jetons stockés pour l'accès à l'API. + +## Gérer l'identité Facebook de l'utilisateur \{#manage-user-s-facebook-identity} + +Après qu'un utilisateur a lié son compte Facebook, les administrateurs peuvent gérer cette connexion dans la Console Logto : + +1. Accédez à Gestion des utilisateurs et ouvrez le profil de l'utilisateur. +2. Sous **Connexions sociales**, localisez l'élément Facebook et cliquez sur **Gérer**. +3. Sur cette page, les administrateurs peuvent gérer la connexion Facebook de l'utilisateur, voir toutes les informations de profil accordées et synchronisées depuis son compte Facebook, et vérifier le statut du jeton d’accès. + +:::note +La réponse du jeton d’accès de Facebook n'inclut pas l'information spécifique sur la portée (scope), donc Logto ne peut pas afficher directement la liste des permissions accordées par l'utilisateur. Cependant, tant que l'utilisateur a consenti aux portées demandées lors de l'autorisation, votre application disposera des permissions correspondantes lors de l'accès à l'API Facebook. Il est recommandé de configurer avec précision les portées requises à la fois dans la Console développeur Facebook et dans Logto afin de garantir que votre application dispose des accès nécessaires. +::: + +## Référence \{#reference} + +Facebook for Developers - Documentation -- [Connexion Facebook - Documentation - Facebook pour les développeurs](https://developers.facebook.com/docs/facebook-login/) - - [Construire manuellement un flux de connexion](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [Guide des permissions](https://developers.facebook.com/docs/facebook-login/guides/permissions) +Documentation Facebook Login diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index c7d5ecb832f..0309ca0cca2 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,55 +1,100 @@ -### Enregistrez un compte développeur Facebook \{#register-a-facebook-developer-account} +## Étape 1 : Configurer une application sur le Facebook App Dashboard \{#step-1-set-up-an-app-on-facebook-app-dashboard} -[Inscrivez-vous en tant que développeur Facebook](https://developers.facebook.com/docs/development/register/) si vous n'en avez pas déjà un +Avant de pouvoir utiliser Facebook comme fournisseur d’authentification, vous devez configurer une application sur la plateforme développeur Facebook afin d’obtenir des identifiants OAuth 2.0. -### Configurez une application Facebook \{#set-up-a-facebook-app} +1. [Inscrivez-vous en tant que développeur Facebook](https://developers.facebook.com/docs/development/register/) si vous n’avez pas encore de compte. +2. Rendez-vous sur la page [Applications](https://developers.facebook.com/apps). +3. Cliquez sur votre application existante ou [créez-en une nouvelle](https://developers.facebook.com/docs/development/create-an-app) si nécessaire. -1. Visitez la page [Apps](https://developers.facebook.com/apps). -2. Cliquez sur votre application existante ou [créez-en une nouvelle](https://developers.facebook.com/docs/development/create-an-app) si nécessaire. - - Le [type d'application](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types) sélectionné dépend de vous, mais il doit inclure le produit _Facebook Login_. -3. Sur la page du tableau de bord de l'application, faites défiler jusqu'à la section "Ajouter un produit" et cliquez sur le bouton "Configurer" sur la carte "Facebook Login". -4. Passez la page de démarrage rapide de Facebook Login, et cliquez sur la barre latérale -> "Produits" -> "Facebook Login" -> "Paramètres". -5. Dans la page des paramètres de Facebook Login, remplissez `${your_logto_origin}/callback/${connector_id}` dans le champ "Valid OAuth Redirect URIs". Le `connector_id` peut être trouvé sur la barre supérieure de la page des détails du connecteur dans la Logto Admin Console. Par exemple : - - `https://logto.dev/callback/${connector_id}` pour la production - - `https://localhost:3001/callback/${connector_id}` pour les tests en environnement local -6. Cliquez sur le bouton "Enregistrer les modifications" en bas à droite. +:::tip +Un cas d’utilisation est la manière principale dont votre application interagira avec Meta et détermine quelles API, fonctionnalités, permissions et produits sont disponibles pour votre application. Si vous avez seulement besoin de l’authentification sociale (pour obtenir email & public_profile), sélectionnez "Authentication and request data from users with Facebook Login". Si vous souhaitez accéder aux API Facebook, choisissez vos cas d’utilisation préférés – la plupart d’entre eux prennent également en charge l’intégration de "Facebook Login for business" après la création de l’application. +::: -## Composer le JSON du connecteur \{#compose-the-connector-json} +4. Après la création de l’application, sur la page du tableau de bord de l’application, accédez à **Cas d’utilisation > Facebook Login > Paramètres** ou **Facebook Login for business > Paramètres**. +5. Remplissez le champ **Valid OAuth Redirect URIs** avec l’**URI de rappel** Logto (copiez-le depuis votre connecteur Facebook Logto). Après que les utilisateurs se soient connectés avec Facebook, ils seront redirigés ici avec un code d’autorisation que Logto utilise pour terminer l’authentification. +6. Accédez à **Cas d’utilisation** et cliquez sur **Personnaliser** de votre cas d’utilisation pour ajouter les portées (scopes). Nous recommandons d’ajouter `email` et `public_profile` qui sont nécessaires pour implémenter la connexion avec Facebook dans Logto. -1. Dans la page du tableau de bord de l'application Facebook, cliquez sur la barre latérale -> "Paramètres" -> "Basique". -2. Vous verrez l'"ID de l'application" et le "Secret de l'application" sur le panneau. -3. Cliquez sur le bouton "Afficher" suivant la boîte de saisie du Secret de l'application pour copier son contenu. -4. Remplissez les paramètres du connecteur Logto : - - Remplissez le champ `clientId` avec la chaîne de l'_ID de l'application_. - - Remplissez le champ `clientSecret` avec la chaîne du _Secret de l'application_. - - Remplissez le champ `scope` avec une liste de [permissions](https://developers.facebook.com/docs/permissions/reference) séparées par des virgules ou des espaces sous forme de chaîne. Si vous ne spécifiez pas de portée, la portée par défaut est `email,public_profile`. +## Étape 2 : Configurer le connecteur Logto avec les identifiants client \{#step-2-set-up-logto-connector-with-client-credentials} -## Tester la connexion avec les utilisateurs de test de Facebook \{#test-sign-in-with-facebooks-test-users} +1. Dans le Facebook App Dashboard, cliquez sur la barre latérale **Paramètres de l’application > Basique**. +2. Vous verrez l’**ID de l’application** et le **Secret de l’application** sur le panneau. +3. Cliquez sur le bouton **Afficher** à côté du champ Secret de l’application pour révéler et copier son contenu. +4. Configurez les paramètres de votre connecteur Facebook Logto : + - Remplissez le champ `clientId` avec l’**ID de l’application**. + - Remplissez le champ `clientSecret` avec le **Secret de l’application**. + - Cliquez sur **Enregistrer et Terminer** dans Logto pour connecter votre système d’identité à Facebook. -Vous pouvez utiliser les comptes des utilisateurs de test, développeurs et administrateurs pour tester la connexion avec l'application concernée à la fois en [mode développement et en mode live](https://developers.facebook.com/docs/development/build-and-test/app-modes). +## Étape 3 : Configurer les portées (scopes) \{#step-3-configure-scopes} -Vous pouvez également [mettre l'application en ligne](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode) directement afin que tout utilisateur Facebook puisse se connecter avec l'application. +Les portées définissent les permissions que votre application demande aux utilisateurs et contrôlent quelles données privées votre projet peut accéder depuis leurs comptes Facebook. -- Dans la page du tableau de bord de l'application, cliquez sur la barre latérale -> "Rôles" -> "Utilisateurs de test". -- Cliquez sur le bouton "Créer des utilisateurs de test" pour créer un utilisateur de test. -- Cliquez sur le bouton "Options" de l'utilisateur de test existant, et vous verrez plus d'opérations, par exemple, "Changer le nom et le mot de passe". +### Configurer les portées dans le Facebook App Dashboard \{#configure-scopes-in-facebook-app-dashboard} -## Publier les paramètres de connexion Facebook \{#publish-facebook-sign-in-settings} +1. Accédez à **Facebook App Dashboard > Cas d’utilisation** et cliquez sur le bouton **Personnaliser**. +2. Ajoutez uniquement les portées dont votre application a besoin. Les utilisateurs examineront et autoriseront ces permissions sur l’écran de consentement Facebook : + - **Pour l’authentification (Obligatoire)** : `email` et `public_profile`. + - **Pour l’accès à l’API (Optionnel)** : Toute portée supplémentaire dont votre application a besoin (par exemple, `threads_content_publish`, `threads_read_replies` pour accéder à l’API Threads). Parcourez la [documentation développeur Meta](https://developers.facebook.com/docs/) pour les services disponibles. -Habituellement, seuls les utilisateurs de test, administrateurs et développeurs peuvent se connecter avec l'application concernée en [mode développement](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode). +### Configurer les portées dans Logto \{#configure-scopes-in-logto} -Pour permettre aux utilisateurs Facebook normaux de se connecter avec l'application dans l'environnement de production, vous devrez peut-être passer votre application Facebook en _[mode live](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_, selon le type d'application. -Par exemple, l'application de type purement _business_ n'a pas le bouton de basculement "live", mais cela ne bloquera pas votre utilisation. +Choisissez une ou plusieurs des approches suivantes selon vos besoins : -1. Dans la page du tableau de bord de l'application Facebook, cliquez sur la barre latérale -> "Paramètres" -> "Basique". -2. Remplissez les champs "URL de la politique de confidentialité" et "Suppression des données utilisateur" sur le panneau si nécessaire. -3. Cliquez sur le bouton "Enregistrer les modifications" en bas à droite. -4. Cliquez sur le bouton de basculement "Live" sur la barre supérieure de l'application. +**Option 1 : Aucune portée API supplémentaire requise** -## Types de configuration \{#config-types} +- Laissez le champ `Scopes` vide dans votre connecteur Facebook Logto. +- La portée par défaut `email public_profile` sera demandée pour garantir que Logto puisse obtenir correctement les informations de base de l’utilisateur. -| Nom | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**Option 2 : Demander des portées supplémentaires à la connexion** + +- Entrez toutes les portées souhaitées dans le champ **Scopes**, séparées par des espaces. +- Toute portée que vous indiquez ici remplace les valeurs par défaut, donc incluez toujours les portées d’authentification : `email public_profile`. + +**Option 3 : Demander des portées supplémentaires ultérieurement** + +- Après la connexion de l’utilisateur, vous pouvez demander des portées supplémentaires à la demande en réinitiant un flux d’autorisation sociale fédérée et en mettant à jour l’ensemble de jetons stockés de l’utilisateur. +- Ces portées supplémentaires n’ont pas besoin d’être renseignées dans le champ `Scopes` de votre connecteur Facebook Logto, et peuvent être obtenues via l’API de vérification sociale de Logto. + +En suivant ces étapes, votre connecteur Facebook Logto demandera exactement les permissions dont votre application a besoin – ni plus, ni moins. + +:::tip +Si votre application demande ces portées pour accéder à l’API Facebook et effectuer des actions, assurez-vous d’activer **Stocker les jetons pour un accès API persistant** dans le connecteur Facebook Logto. Voir la section suivante pour plus de détails. +::: + +## Étape 4 : Paramètres généraux \{#step-4-general-settings} + +Voici quelques paramètres généraux qui ne bloqueront pas la connexion à Facebook mais peuvent affecter l’expérience d’authentification de l’utilisateur final. + +### Synchroniser les informations du profil \{#sync-profile-information} + +Dans le connecteur Facebook, vous pouvez définir la politique de synchronisation des informations du profil, telles que les noms d’utilisateur et les avatars. Choisissez parmi : + +- **Synchroniser uniquement à l’inscription** : Les informations du profil sont récupérées une seule fois lors de la première connexion de l’utilisateur. +- **Toujours synchroniser à la connexion** : Les informations du profil sont mises à jour à chaque connexion de l’utilisateur. + +### Stocker les jetons pour accéder aux API Facebook (Optionnel) \{#store-tokens-to-access-facebook-apis-optional} + +Si vous souhaitez accéder aux API Facebook et effectuer des actions avec l’autorisation de l’utilisateur (que ce soit via la connexion sociale ou la liaison de compte), Logto doit obtenir des portées API spécifiques et stocker les jetons. + +1. Ajoutez les portées requises en suivant le tutoriel ci-dessus. +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur Facebook Logto. Logto stockera en toute sécurité les jetons d’accès Facebook dans le Secret Vault. + +:::note +Facebook ne fournit pas de jetons de rafraîchissement. Cependant, lorsque le stockage des jetons est activé, Logto demande automatiquement un jeton d’accès longue durée (60 jours) lors de l’authentification de l’utilisateur. Pendant cette période, les utilisateurs peuvent révoquer manuellement les jetons d’accès, mais n’auront sinon pas besoin de ré-autorisation pour accéder aux API Facebook. Remarque : N’ajoutez pas `offline_access` au champ `Scope` car cela peut provoquer des erreurs. +::: + +## Étape 5 : Tester la connexion avec les utilisateurs de test Facebook (Optionnel) \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +Vous pouvez utiliser des comptes utilisateur de test, développeur et administrateur pour tester la connexion avec l’application. Vous pouvez également publier l’application directement afin que tout utilisateur Facebook puisse se connecter. + +1. Dans le Facebook App Dashboard, cliquez sur la barre latérale **Rôles de l’application > Utilisateurs de test**. +2. Cliquez sur le bouton **Créer des utilisateurs de test** pour créer un utilisateur de test. +3. Cliquez sur le bouton **Options** d’un utilisateur de test existant pour voir plus d’opérations, telles que "Changer le nom et le mot de passe". + +## Étape 6 : Publier les paramètres de connexion Facebook \{#step-6-publish-facebook-sign-in-settings} + +En général, seuls les utilisateurs de test, administrateurs et développeurs peuvent se connecter avec l’application. Pour permettre aux utilisateurs Facebook normaux de se connecter avec l’application en environnement de production, vous devrez peut-être publier cette application. + +1. Dans le Facebook App Dashboard, cliquez sur la barre latérale **Publier**. +2. Remplissez les champs **URL de la politique de confidentialité** et **Suppression des données utilisateur** si nécessaire. +3. Cliquez sur le bouton **Enregistrer les modifications** en bas à droite. +4. Cliquez sur le bouton **Live** dans la barre supérieure de l’application. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index e5511a08e98..09ba793c2b3 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -11,28 +11,73 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configurer la connexion sociale avec GitHub +# Configurer la connexion sociale avec GitHub (Set up social login with GitHub) -Le connecteur officiel Logto pour la connexion sociale GitHub. +Intégrez l’application GitHub OAuth pour activer la connexion avec GitHub, la liaison de comptes et l’accès sécurisé aux API GitHub. ## Commencer \{#get-started} -Le connecteur GitHub permet aux utilisateurs finaux de se connecter à votre application en utilisant leurs propres comptes GitHub via le protocole d'authentification OAuth 2.0 de GitHub. +Le connecteur GitHub permet l’intégration OAuth 2.0 pour que votre application puisse : + +- Ajouter l’authentification "Connexion avec GitHub" +- Lier les comptes utilisateurs aux identités GitHub +- Synchroniser les informations de profil utilisateur depuis GitHub +- Accéder aux API GitHub via le stockage sécurisé des jetons dans le Secret Vault de Logto pour les tâches d’automatisation (par exemple, créer des issues GitHub, gérer des dépôts depuis votre application) + +Pour configurer ces fonctionnalités d’authentification, créez d’abord un connecteur GitHub dans Logto : + +1. Allez dans Console Logto > Connecteur > Connecteur social. +2. Cliquez sur **Ajouter un connecteur social**, sélectionnez **GitHub**, cliquez sur **Suivant**, puis suivez le tutoriel étape par étape pour terminer l’intégration. -## Tester le connecteur GitHub \{#test-github-connector} +## Utiliser le connecteur GitHub \{#utilize-the-github-connector} + +Une fois que vous avez créé un connecteur GitHub et que vous l’avez connecté à GitHub, vous pouvez l’intégrer dans vos parcours utilisateurs. Choisissez les options qui correspondent à vos besoins : + +### Activer "Connexion avec GitHub" \{#enable-sign-in-with-github} + +1. Dans la Console Logto, allez dans Expérience de connexion > Inscription et connexion. +2. Ajoutez le connecteur GitHub dans la section **Connexion sociale** pour permettre aux utilisateurs de s’authentifier avec GitHub. + +En savoir plus sur [l’expérience de connexion sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Lier ou délier un compte GitHub \{#link-or-unlink-a-github-account} + +Utilisez l’Account API pour construire un Centre de compte personnalisé dans votre application permettant aux utilisateurs connectés de lier ou délier leur compte GitHub. [Suivez le tutoriel Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -C'est tout. Le connecteur GitHub devrait être disponible maintenant. N'oubliez pas de [Activer le connecteur social dans l'expérience de connexion](/connectors/social-connectors/#enable-social-sign-in). +:::tip +Il est possible d’activer le connecteur GitHub uniquement pour la liaison de compte et l’accès à l’API, sans l’activer pour la connexion sociale. +::: + +### Accéder aux API GitHub et effectuer des actions \{#access-github-apis-and-perform-actions} + +Votre application peut récupérer les jetons d’accès GitHub stockés dans le Secret Vault pour appeler les API GitHub et automatiser des tâches backend (par exemple, créer des issues, gérer des dépôts ou automatiser des workflows). Consultez le guide sur la récupération des jetons stockés pour l’accès à l’API. + +## Gérer l’identité GitHub de l’utilisateur \{#manage-user-s-github-identity} + +Après qu’un utilisateur a lié son compte GitHub, les administrateurs peuvent gérer cette connexion dans la Console Logto : + +1. Accédez à Console Logto > Gestion des utilisateurs et ouvrez le profil de l’utilisateur. +2. Sous **Connexions sociales**, localisez l’élément GitHub et cliquez sur **Gérer**. +3. Sur cette page, les administrateurs peuvent gérer la connexion GitHub de l’utilisateur, voir toutes les informations de profil accordées et synchronisées depuis leur compte GitHub, et vérifier le statut du jeton d’accès. + +:::note +La réponse du jeton d’accès de GitHub n’inclut pas l’information spécifique sur la portée (scope), donc Logto ne peut pas afficher directement la liste des permissions accordées par l’utilisateur. Cependant, tant que l’utilisateur a consenti aux portées demandées lors de l’autorisation, votre application disposera des permissions correspondantes lors de l’accès à l’API GitHub. +::: ## Référence \{#reference} - GitHub - Développeurs - Applications + Documentation développeur GitHub - À propos des Apps - GitHub - Développeurs - Applications - Création d'une application OAuth + Documentation développeur GitHub - Créer une application OAuth + + + + Documentation sur les portées des applications OAuth GitHub diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index 75279a705cb..e6af6817eed 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,35 +1,99 @@ -### Se connecter avec un compte GitHub \{#sign-in-with-github-account} +## Étape 1 : Créer une application OAuth sur GitHub \{#step-1-create-an-oauth-app-on-github} -Allez sur le [site GitHub](https://github.com/) et connectez-vous avec votre compte GitHub. Vous pouvez créer un nouveau compte si vous n'en avez pas. +Avant de pouvoir utiliser GitHub comme fournisseur d'authentification, vous devez créer une application OAuth sur GitHub pour obtenir des identifiants OAuth 2.0. -### Créer et configurer une application OAuth \{#create-and-configure-oauth-app} +1. Rendez-vous sur [GitHub](https://github.com/) et connectez-vous avec votre compte, ou créez un nouveau compte si nécessaire. +2. Accédez à [Paramètres > Paramètres développeur > Applications OAuth](https://github.com/settings/developers). +3. Cliquez sur **Nouvelle application OAuth** pour enregistrer une nouvelle application : + - **Nom de l'application** : Saisissez un nom descriptif pour votre application. + - **URL de la page d'accueil** : Saisissez l'URL de la page d'accueil de votre application. + - **URL de rappel d'autorisation** : Copiez l'**URI de rappel** depuis votre connecteur GitHub Logto et collez-le ici. Après la connexion des utilisateurs avec GitHub, ils seront redirigés ici avec un code d'autorisation que Logto utilise pour finaliser l'authentification. + - **Description de l'application** : (Optionnel) Ajoutez une brève description de votre application. +4. Cliquez sur **Enregistrer l'application** pour créer l'application OAuth. -Suivez le guide [création d'une application OAuth](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) et enregistrez une nouvelle application. +:::note +Nous vous recommandons de ne pas cocher la case **Activer Device Flow**, car les utilisateurs qui se connectent avec GitHub sur des appareils mobiles devront confirmer l'action de connexion initiale dans l'application mobile GitHub. De nombreux utilisateurs GitHub n'installent pas l'application mobile GitHub sur leur téléphone, ce qui pourrait bloquer le flux de connexion. Activez cette option uniquement si vous attendez des utilisateurs finaux qu'ils confirment leur connexion via l'application mobile GitHub. Voir les détails sur le [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). -Nommez votre nouvelle application OAuth dans **Nom de l'application** et remplissez l'**URL de la page d'accueil** de l'application. Vous pouvez laisser le champ **Description de l'application** vide et personnaliser l'**URL de rappel d'autorisation** comme `${your_logto_origin}/callback/${connector_id}`. Le `connector_id` peut être trouvé sur la barre supérieure de la page des détails du connecteur dans la Logto Admin Console. +Pour plus de détails sur la configuration des applications OAuth GitHub, consultez [Créer une application OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). +::: -:::note +## Étape 2 : Configurer votre connecteur Logto \{#step-2-configure-your-logto-connector} + +Après avoir créé l'application OAuth sur GitHub, vous serez redirigé vers une page de détails où vous pourrez copier l'ID client et générer un secret client. + +1. Copiez l'**ID client** de votre application OAuth GitHub et collez-le dans le champ `clientId` dans Logto. +2. Cliquez sur **Générer un nouveau secret client** sur GitHub pour créer un nouveau secret, puis copiez-le et collez-le dans le champ `clientSecret` dans Logto. +3. Cliquez sur **Enregistrer et Terminer** dans Logto pour connecter votre système d'identité à GitHub. + +:::warning +Gardez votre secret client en sécurité et ne l'exposez jamais dans du code côté client. Les secrets client GitHub ne peuvent pas être récupérés s'ils sont perdus — vous devrez en générer un nouveau. +::: + +## Étape 3 : Configurer les portées (Optionnel) \{#step-3-configure-scopes-optional} + +Les portées (Scopes) définissent les permissions que votre application demande aux utilisateurs et contrôlent les données auxquelles votre application peut accéder depuis leurs comptes GitHub. + +Utilisez le champ `Scopes` dans Logto pour demander des permissions supplémentaires à GitHub. Choisissez l'une des approches suivantes selon vos besoins : + +### Option 1 : Aucune portée API supplémentaire requise \{#option-1-no-extra-api-scopes-needed} + +- Laissez le champ `Scopes` vide dans votre connecteur GitHub Logto. +- La portée par défaut `read:user` sera demandée pour garantir que Logto puisse obtenir correctement les informations de base de l'utilisateur (par exemple, e-mail, nom, avatar). -Si vous rencontrez le message d'erreur "L'URL de redirection DOIT correspondre à l'URL de rappel enregistrée pour cette application." lors de la connexion, essayez d'aligner l'URL de rappel d'autorisation de votre application OAuth GitHub et l'URL de redirection de votre application Logto (bien sûr, y compris le protocole) pour résoudre le problème. +### Option 2 : Demander des portées supplémentaires à la connexion \{#option-2-request-additional-scopes-at-sign-in} +- Parcourez toutes les [portées GitHub disponibles pour les applications OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) et ajoutez uniquement celles dont votre application a besoin. +- Saisissez toutes les portées souhaitées dans le champ **Scopes**, séparées par des espaces. +- Toutes les portées que vous indiquez ici remplacent les valeurs par défaut, donc incluez toujours la portée d'authentification : `read:user`. +- Les portées supplémentaires courantes incluent : + - `repo` : Contrôle total des dépôts privés + - `public_repo` : Accès aux dépôts publics + - `user:email` : Accès aux adresses e-mail de l'utilisateur + - `notifications` : Accès aux notifications +- Assurez-vous que toutes les portées sont correctement orthographiées et valides. Une portée incorrecte ou non prise en charge entraînera une erreur "Invalid scope" de la part de GitHub. + +### Option 3 : Demander des portées incrémentielles ultérieurement \{#option-3-request-incremental-scopes-later} + +- Après la connexion de l'utilisateur, vous pouvez demander des portées supplémentaires à la demande en relançant un flux d'autorisation sociale fédérée et en mettant à jour l'ensemble de jetons stockés de l'utilisateur. +- Ces portées supplémentaires n'ont pas besoin d'être renseignées dans le champ `Scopes` de votre connecteur GitHub Logto, et peuvent être obtenues via l’API de vérification sociale de Logto. + +En suivant ces étapes, votre connecteur GitHub Logto demandera exactement les permissions dont votre application a besoin — ni plus, ni moins. + +:::tip +Si votre application demande ces portées pour accéder à l’API GitHub et effectuer des actions, assurez-vous d’activer **Stocker les jetons pour un accès API persistant** dans le connecteur GitHub Logto. Voir la section suivante pour plus de détails. ::: -Nous vous suggérons de ne pas cocher la case devant **Activer le flux de périphérique**, sinon les utilisateurs qui se connectent avec GitHub sur des appareils mobiles devront confirmer l'action de connexion initiale dans l'application GitHub. De nombreux utilisateurs de GitHub n'installent pas l'application mobile GitHub sur leurs téléphones, ce qui pourrait bloquer le flux de connexion. Veuillez ignorer notre suggestion si vous attendez que les utilisateurs finaux confirment leur flux de connexion. Voir les détails du [flux de périphérique](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). +## Étape 4 : Paramètres généraux \{#step-4-general-settings} + +Voici quelques paramètres généraux qui ne bloqueront pas la connexion à GitHub mais peuvent affecter l'expérience d'authentification des utilisateurs finaux. + +### Synchroniser les informations de profil \{#sync-profile-information} -### Gérer les applications OAuth \{#managing-oauth-apps} +Dans le connecteur GitHub, vous pouvez définir la politique de synchronisation des informations de profil, telles que les noms d'utilisateur et les avatars. Choisissez parmi : -Allez sur la [page des applications OAuth](https://github.com/settings/developers) et vous pouvez ajouter, modifier ou supprimer des applications OAuth existantes. Vous pouvez également trouver le `Client ID` et générer des `Client secrets` dans les pages de détails des applications OAuth. +- **Synchroniser uniquement à l'inscription** : Les informations de profil sont récupérées une seule fois lors de la première connexion de l'utilisateur. +- **Toujours synchroniser à la connexion** : Les informations de profil sont mises à jour à chaque connexion de l'utilisateur. -### Configurer votre connecteur \{#configure-your-connector} +### Stocker les jetons pour accéder aux API GitHub (Optionnel) \{#store-tokens-to-access-github-apis-optional} + +Si vous souhaitez accéder aux API GitHub et effectuer des actions avec l'autorisation de l'utilisateur (que ce soit via la connexion sociale ou la liaison de compte), Logto doit obtenir des portées API spécifiques et stocker les jetons. + +1. Ajoutez les portées requises en suivant les instructions ci-dessus. +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur GitHub Logto. Logto stockera en toute sécurité les jetons d’accès GitHub dans le Secret Vault. + +:::note +Lorsque vous utilisez une **application OAuth GitHub** comme décrit dans ce tutoriel, vous ne pouvez pas obtenir de jeton de rafraîchissement de GitHub car son jeton d’accès n’expire pas, sauf si l’utilisateur le révoque manuellement. Par conséquent, il n’est pas nécessaire d’ajouter `offline_access` dans le champ `Scopes` — le faire peut provoquer une erreur. + +Si vous souhaitez que le jeton d’accès expire ou utiliser des jetons de rafraîchissement, envisagez d’intégrer une **application GitHub** à la place. Découvrez les [différences entre les applications GitHub et les applications OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). +::: -Remplissez le champ `clientId` et `clientSecret` avec le _Client ID_ et le _Client Secret_ que vous avez obtenus à partir des pages de détails des applications OAuth mentionnées dans la section précédente. +## Étape 5 : Tester votre intégration (Optionnel) \{#step-5-test-your-integration-optional} -`scope` est une liste délimitée par des espaces de [portées](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). Si elle n'est pas fournie, la portée par défaut est `read:user`. +Avant de passer en production, testez votre intégration GitHub : -### Types de configuration \{#config-types} +1. Utilisez le connecteur dans un tenant de développement Logto. +2. Vérifiez que les utilisateurs peuvent se connecter avec GitHub. +3. Vérifiez que les bonnes portées sont demandées. +4. Testez les appels API si vous stockez des jetons. -| Nom | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +Les applications OAuth GitHub fonctionnent immédiatement avec n'importe quel compte utilisateur GitHub — il n'est pas nécessaire d'avoir des utilisateurs de test ou une approbation d'application comme sur d'autres plateformes. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index 5c4af9f3f8d..ccd1440493b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -2,8 +2,8 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: - description: Google est un principal fournisseur de technologies de moteur de recherche et de services de messagerie électronique. -tutorial_config_name: Google OAuth app + description: Google est un fournisseur majeur de technologies de moteur de recherche et de services de messagerie électronique. +tutorial_config_name: Application OAuth Google --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -12,14 +12,66 @@ import Integration from './_integration.mdx'; # Configurer la connexion sociale avec Google -Le connecteur Google offre un moyen succinct pour votre application d'utiliser le système d'authentification OAuth 2.0 de Google. +Intégrez le système d’authentification OAuth 2.0 de Google pour activer la connexion avec Google, la liaison de comptes et l’accès sécurisé aux API Google. +## Commencer \{#get-started} + +Le connecteur Google permet l’intégration OAuth 2.0 afin de permettre à votre application de : + +- Ajouter l’authentification "Connexion avec Google" +- Lier les comptes utilisateurs aux identités Google +- Synchroniser les informations de profil utilisateur depuis Google +- Accéder aux API Google via le stockage sécurisé des jetons dans le Secret Vault de Logto pour des tâches d’automatisation (par exemple, modifier des documents Google Docs, gérer des événements Calendrier dans votre application) + +Pour configurer ces fonctionnalités d’authentification, créez d’abord un connecteur Google dans Logto : + +1. Rendez-vous sur Console Logto > Connecteur > Connecteur social. +2. Cliquez sur **Ajouter un connecteur social**, sélectionnez **Google**, cliquez sur **Suivant** et suivez le tutoriel étape par étape pour finaliser l’intégration. + -## Références \{#references} +## Utiliser le connecteur Google \{#utilize-the-google-connector} + +Une fois que vous avez créé un connecteur Google et que vous l’avez connecté à Google, vous pouvez l’intégrer dans vos parcours utilisateurs. Choisissez les options qui correspondent à vos besoins : + +### Activer "Connexion avec Google" \{#enable-sign-in-with-google} + +1. Dans la Console Logto, allez sur Expérience de connexion > Inscription et connexion. +2. Ajoutez le connecteur Google dans la section **Connexion sociale** pour permettre aux utilisateurs de s’authentifier avec Google. +3. Activez éventuellement **Google One Tap** sur les pages de connexion et d’inscription pour une expérience d’authentification simplifiée. + +En savoir plus sur [l’expérience de connexion sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Lier ou délier un compte Google \{#link-or-unlink-a-google-account} + +Utilisez l’Account API pour construire un Centre de compte personnalisé dans votre application permettant aux utilisateurs connectés de lier ou délier leur compte Google. [Suivez le tutoriel Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Il est possible d’activer le connecteur Google uniquement pour la liaison de compte et l’accès à l’API, sans l’activer pour la connexion sociale. +::: + +### Accéder aux API Google et effectuer des actions \{#access-google-apis-and-perform-actions} + +Votre application peut récupérer les jetons d’accès Google stockés dans le Secret Vault pour appeler les API Google et automatiser des tâches backend (par exemple, gérer des fichiers Google Drive, créer des événements Calendrier ou envoyer des e-mails via Gmail). Consultez le guide sur la récupération des jetons stockés pour l’accès à l’API. + +## Gérer l’identité Google de l’utilisateur \{#manage-user-s-google-identity} + +Après qu’un utilisateur a lié son compte Google, les administrateurs peuvent gérer cette connexion dans la Console Logto : + +1. Accédez à Console Logto > Gestion des utilisateurs et ouvrez le profil de l’utilisateur. +2. Sous **Connexions sociales**, localisez l’élément Google et cliquez sur **Gérer**. +3. Sur cette page, les administrateurs peuvent gérer la connexion Google de l’utilisateur, voir toutes les informations de profil accordées et synchronisées depuis son compte Google, et vérifier le statut du jeton d’accès. + +## Référence \{#reference} - Google Identity : Configuration d'OAuth 2.0 + Google Identity : Configuration OAuth 2.0 + + + Google Identity Services (One Tap) + + +Google Cloud Console diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index 7a25029a402..9bda962bb5d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## Configurer un projet dans la Google API Console \{#set-up-a-project-in-the-google-api-console} +## Étape 1 : Créer un projet sur la plateforme Google Auth \{#step-1-create-a-project-on-google-auth-platform} + +Avant de pouvoir utiliser Google comme fournisseur d'authentification, vous devez configurer un projet dans la Google Cloud Console afin d'obtenir des identifiants OAuth 2.0. Si vous avez déjà un projet, vous pouvez passer cette étape. + +1. Rendez-vous sur la [Google Cloud Console](https://console.cloud.google.com/) et connectez-vous avec votre compte Google. +2. Cliquez sur le bouton **Sélectionner un projet** dans la barre de menu supérieure, puis cliquez sur le bouton **Nouveau projet** pour créer un projet. +3. Dans votre nouveau projet, accédez à **APIs & Services > Écran de consentement OAuth** pour configurer votre application : + - **Informations sur l'application** : Saisissez le **Nom de l'application** et l'**E-mail de support** qui seront affichés sur la page de consentement. + - **Audience (Audience)** : Sélectionnez le type d'audience souhaité : + - **Interne** – Uniquement pour les utilisateurs Google Workspace au sein de votre organisation + - **Externe** – Pour tout utilisateur Google (nécessite une vérification pour une utilisation en production) + - **Informations de contact** : Fournissez des adresses e-mail afin que Google puisse vous notifier de tout changement concernant votre projet. + - Cochez **J'accepte les politiques de Google** pour terminer la configuration de base. +4. Facultativement, allez dans la section **Branding** pour modifier les informations du produit et téléchargez votre **Logo d'application**, qui apparaîtra sur l'écran de consentement OAuth pour aider les utilisateurs à reconnaître votre application. + +:::tip +Si vous choisissez le type d'audience **Externe**, vous devrez ajouter des utilisateurs de test pendant le développement et publier votre application pour une utilisation en production. +::: + +## Étape 2 : Créer des identifiants OAuth 2.0 \{#step-2-create-oauth-2-0-credentials} + +Accédez à la page [Identifiants](https://console.cloud.google.com/apis/credentials) dans la Google Cloud Console et créez des identifiants OAuth pour votre application. + +1. Cliquez sur **Créer des identifiants > ID client OAuth**. +2. Sélectionnez **Application Web** comme type d'application. +3. Renseignez le **Nom** de votre client OAuth. Cela vous aide à identifier les identifiants et n'est pas affiché aux utilisateurs finaux. +4. Configurez les URI autorisés : + - **Origines JavaScript autorisées** : Ajoutez l'origine de votre instance Logto (par exemple, `https://votre-domaine-logto.com`) + - **URI de redirection autorisés** : Ajoutez l'**URI de rappel** Logto (copiez-le depuis votre connecteur Google Logto) +5. Cliquez sur **Créer** pour générer le client OAuth. + +## Étape 3 : Configurer le connecteur Logto avec les identifiants \{#step-3-configure-logto-connector-with-credentials} + +Après avoir créé le client OAuth, Google affichera une fenêtre modale avec vos identifiants : + +1. Copiez l'**ID client** et collez-le dans le champ `clientId` dans Logto. +2. Copiez le **Secret client** et collez-le dans le champ `clientSecret` dans Logto. +3. Cliquez sur **Enregistrer et Terminer** dans Logto pour connecter votre système d'identité à Google. + +:::warning +Gardez votre secret client en sécurité et ne l'exposez jamais dans du code côté client. En cas de compromission, générez-en un nouveau immédiatement. +::: + +## Étape 4 : Configurer les portées (Scopes) \{#step-4-configure-scopes} + +Les portées (Portées) définissent les permissions que votre application demande aux utilisateurs et contrôlent les données auxquelles votre application peut accéder depuis leurs comptes Google. + +### Configurer les portées dans la Google Cloud Console \{#configure-scopes-in-google-cloud-console} + +1. Accédez à **APIs & Services > Écran de consentement OAuth > Portées**. +2. Cliquez sur **Ajouter ou supprimer des portées** et sélectionnez uniquement les portées requises par votre application : + - **Authentification (Authentification) (Obligatoire)** : + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **Accès API (Optionnel)** : Ajoutez toute portée supplémentaire nécessaire à votre application (par exemple, Drive, Calendar, YouTube). Parcourez la [bibliothèque d'API Google](https://console.cloud.google.com/apis/library) pour trouver les services disponibles. Si votre application a besoin d'accéder à des API Google au-delà des permissions de base, activez d'abord les API spécifiques que votre application utilisera (par exemple, Google Drive API, Gmail API, Calendar API) dans la bibliothèque d'API Google. +3. Cliquez sur **Mettre à jour** pour confirmer la sélection. +4. Cliquez sur **Enregistrer et continuer** pour appliquer les modifications. -- Visitez la [Google API Console](https://console.developers.google.com) et connectez-vous avec votre compte Google. -- Cliquez sur le bouton **Sélectionner un projet** dans la barre de menu supérieure, puis cliquez sur le bouton **Nouveau projet** pour créer un projet. -- Dans votre nouveau projet, cliquez sur **APIs & Services** pour entrer dans le menu **APIs & Services**. +### Configurer les portées dans Logto \{#configure-scopes-in-logto} -## Configurer votre écran de consentement \{#configure-your-consent-screen} +Choisissez une ou plusieurs des approches suivantes selon vos besoins : -### Configurer et enregistrer votre application \{#configure-and-register-your-application} +**Option 1 : Aucune portée API supplémentaire requise** -- Dans le menu de gauche **APIs & Services**, cliquez sur le bouton **Écran de consentement OAuth**. -- Choisissez le **Type d'utilisateur** que vous souhaitez, et cliquez sur le bouton **Créer**. (Remarque : Si vous sélectionnez **Externe** comme **Type d'utilisateur**, vous devrez ajouter des utilisateurs de test plus tard.) +- Laissez le champ `Scopes` vide dans votre connecteur Google Logto. +- Les portées par défaut `openid profile email` seront demandées pour garantir que Logto puisse obtenir correctement les informations de base de l'utilisateur. -Vous serez maintenant sur la page **Modifier l'enregistrement de l'application**. +**Option 2 : Demander des portées supplémentaires à la connexion** -### Modifier l'enregistrement de l'application \{#edit-app-registration} +- Saisissez toutes les portées souhaitées dans le champ **Scopes**, séparées par des espaces. +- Toute portée que vous indiquez ici remplace les valeurs par défaut, donc incluez toujours les portées d'authentification : `https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`. +- Utilisez les URL complètes des portées. Exemple : `https://www.googleapis.com/auth/calendar.readonly`. -#### Configurer l'écran de consentement OAuth \{#config-oauth-consent-screen} +**Option 3 : Demander des portées incrémentielles ultérieurement** -- Suivez les instructions pour remplir le formulaire **Écran de consentement OAuth**. -- Cliquez sur **ENREGISTRER ET CONTINUER** pour continuer. +- Après la connexion de l'utilisateur, vous pouvez demander des portées supplémentaires à la demande en relançant un flux d'autorisation sociale fédérée et en mettant à jour l'ensemble de jetons stockés de l'utilisateur. +- Ces portées supplémentaires n'ont pas besoin d'être renseignées dans le champ `Scopes` de votre connecteur Google Logto, et peuvent être obtenues via l'API de vérification sociale de Logto. -#### Configurer les portées \{#config-scopes} +En suivant ces étapes, votre connecteur Google Logto demandera exactement les permissions dont votre application a besoin — ni plus, ni moins. -- Cliquez sur **AJOUTER OU SUPPRIMER DES PORTÉES** et sélectionnez `../auth/userinfo.email`, `../auth/userinfo.profile` et `openid` dans le tiroir contextuel, puis cliquez sur **METTRE À JOUR** pour terminer. Il est recommandé de considérer l'ajout de toutes les portées que vous pourriez utiliser, sinon certaines portées ajoutées dans la configuration pourraient ne pas fonctionner. -- Remplissez le formulaire selon vos besoins. -- Cliquez sur **ENREGISTRER ET CONTINUER** pour continuer. +:::tip +Si votre application demande ces portées pour accéder à l'API Google et effectuer des actions, assurez-vous d'activer **Stocker les jetons pour un accès API persistant** dans le connecteur Google Logto. Voir la section suivante pour plus de détails. +::: -#### Ajouter des utilisateurs de test (Type d'utilisateur externe uniquement) \{#add-test-users-external-user-type-only} +## Étape 5 : Personnaliser les invites d'authentification \{#step-5-customize-authentication-prompts} -- Cliquez sur **AJOUTER DES UTILISATEURS** et ajoutez des utilisateurs de test pour permettre à ces utilisateurs d'accéder à votre application pendant les tests. -- Cliquez sur **ENREGISTRER ET CONTINUER** pour continuer. +Configurez les **Prompts** dans Logto pour contrôler l'expérience d'authentification utilisateur. Prompts est un tableau de chaînes qui spécifie le type d'interaction utilisateur requise : -Vous devriez maintenant avoir configuré l'écran de consentement Google OAuth 2.0. +- `none` – Le serveur d'autorisation n'affiche aucun écran d'authentification ou de consentement. Retourne une erreur si l'utilisateur n'est pas déjà authentifié et n'a pas préconfiguré le consentement pour les portées demandées. Utilisez ceci pour vérifier l'existence d'une authentification et/ou d'un consentement. +- `consent` – Le serveur d'autorisation invite l'utilisateur à donner son consentement avant de retourner des informations au client. Nécessaire pour activer l'**accès hors ligne** à l'API Google. +- `select_account` – Le serveur d'autorisation invite l'utilisateur à sélectionner un compte utilisateur. Cela permet aux utilisateurs ayant plusieurs comptes Google de choisir celui à utiliser pour l'authentification. -## Obtenir des identifiants OAuth 2.0 \{#obtain-oauth-20-credentials} +## Étape 6 : Paramètres généraux \{#step-6-general-settings} -- Dans le menu de gauche **APIs & Services**, cliquez sur le bouton **Identifiants**. -- Sur la page **Identifiants**, cliquez sur le bouton **+ CRÉER DES IDENTIFIANTS** dans la barre de menu supérieure, et sélectionnez **ID client OAuth**. -- Sur la page **Créer un ID client OAuth**, sélectionnez **Application Web** comme type d'application. -- Remplissez les informations de base pour votre application. -- Cliquez sur **+ Ajouter un URI** pour ajouter un domaine autorisé à la section **Origines JavaScript autorisées**. C'est le domaine à partir duquel votre page d'autorisation Logto sera servie. Dans notre cas, ce sera `${your_logto_origin}`. par exemple `https://logto.dev`. -- Cliquez sur **+ Ajouter un URI** dans la section **URIs de redirection autorisées** pour configurer les **URIs de redirection autorisées**, qui redirigent l'utilisateur vers l'application après la connexion. Dans notre cas, ce sera `${your_logto_endpoint}/callback/${connector_id}`. par exemple `https://logto.dev/callback/${connector_id}`. Le `connector_id` peut être trouvé dans la barre supérieure de la page des détails du connecteur de la Logto Admin Console. -- Cliquez sur **Créer** pour terminer, puis vous obtiendrez le **Client ID** et le **Client Secret**. +Voici quelques paramètres généraux qui ne bloqueront pas la connexion à Google mais peuvent affecter l'expérience d'authentification de l'utilisateur final. -## Configurer votre connecteur \{#configure-your-connector} +### Synchroniser les informations de profil \{#sync-profile-information} -Remplissez les champs `clientId` et `clientSecret` avec le _Client ID_ et le _Client Secret_ que vous avez obtenus des pages de détails de l'application OAuth mentionnées dans la section précédente. +Dans le connecteur Google, vous pouvez définir la politique de synchronisation des informations de profil, telles que les noms d'utilisateur et les avatars. Choisissez parmi : -`scope` est une liste délimitée par des espaces de [portées](https://developers.google.com/identity/protocols/oauth2/scopes). Si non fourni, la portée par défaut est `openid profile email`. +- **Synchroniser uniquement à l'inscription** : Les informations de profil sont récupérées une seule fois lors de la première connexion de l'utilisateur. +- **Toujours synchroniser à la connexion** : Les informations de profil sont mises à jour à chaque connexion de l'utilisateur. -`prompts` est un tableau de chaînes qui spécifie le type d'interaction utilisateur requis. La chaîne peut être l'une des valeurs suivantes : +### Stocker les jetons pour accéder aux API Google (Optionnel) \{#store-tokens-to-access-google-apis-optional} -- `none` : Le serveur d'autorisation n'affiche aucun écran d'authentification ou de consentement utilisateur ; il renverra une erreur si l'utilisateur n'est pas déjà authentifié et n'a pas préconfiguré le consentement pour les portées demandées. Vous pouvez utiliser none pour vérifier l'authentification et/ou le consentement existants. -- `consent` : Le serveur d'autorisation demande le consentement de l'utilisateur avant de renvoyer des informations au client. -- `select_account` : Le serveur d'autorisation demande à l'utilisateur de sélectionner un compte utilisateur. Cela permet à un utilisateur qui a plusieurs comptes sur le serveur d'autorisation de choisir parmi les comptes multiples pour lesquels il peut avoir des sessions en cours. +Si vous souhaitez accéder aux [API Google](https://console.cloud.google.com/apis/library) et effectuer des actions avec l'autorisation de l'utilisateur (que ce soit via la connexion sociale ou la liaison de compte), Logto doit obtenir des portées API spécifiques et stocker les jetons. -### Types de configuration \{#config-types} +1. Ajoutez les portées requises dans la configuration de l'écran de consentement OAuth de votre Google Cloud Console et dans le connecteur Google Logto. +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur Google Logto. Logto stockera en toute sécurité les jetons d'accès et de rafraîchissement Google dans le Secret Vault. +3. Pour garantir le retour des jetons de rafraîchissement, configurez votre connecteur Google Logto comme suit : + - Définissez **Prompts** pour inclure `consent` + - Activez **Accès hors ligne** -| Nom | Type | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +Vous n'avez pas besoin d'ajouter `offline_access` dans le champ `Scope` de Logto — cela peut entraîner une erreur. Google utilise automatiquement `access_type=offline` lorsque l'accès hors ligne est activé. +::: -## Activer Google One Tap \{#enable-google-one-tap} +## Étape 7 : Activer Google One Tap (Optionnel) \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) est un moyen sécurisé et facile de permettre aux utilisateurs de se connecter à votre site Web ou application avec leur compte Google. +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) est un moyen sécurisé et simplifié permettant aux utilisateurs de se connecter à votre site web avec leur compte Google via une interface popup. -Une fois que vous avez configuré le connecteur Google, vous verrez une carte pour Google One Tap dans la page des détails du connecteur. Vous pouvez activer Google One Tap sur vos pages d'inscription et de connexion en basculant l'interrupteur. +Une fois le connecteur Google configuré, vous verrez une carte pour Google One Tap dans la page de détails du connecteur. Activez Google One Tap en basculant l'interrupteur. -Lorsque vous activez Google One Tap, vous pouvez configurer les options suivantes : +### Options de configuration de Google One Tap \{#google-one-tap-configuration-options} -- **Sélection automatique des identifiants si possible** : Connectez automatiquement l'utilisateur avec le compte Google si [certaines conditions sont remplies](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out). -- **Annuler l'invite si l'utilisateur clique / tape à l'extérieur** : Fermez l'invite Google One Tap si l'utilisateur clique ou tape à l'extérieur de l'invite. Si désactivé, l'utilisateur doit cliquer sur le bouton de fermeture pour rejeter l'invite. -- **Activer l'expérience utilisateur améliorée One Tap sur les navigateurs ITP** : Activez l'expérience utilisateur améliorée Google One Tap sur les navigateurs avec prévention intelligente du suivi (ITP). Veuillez vous référer à [cette page](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) pour plus d'informations. +- **Sélection automatique de l'identifiant si possible** – Connecte automatiquement l'utilisateur avec le compte Google si [certaines conditions sont remplies](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) +- **Annuler l'invite si l'utilisateur clique/tape en dehors** – Ferme l'invite Google One Tap si l'utilisateur clique ou tape en dehors de l'invite. Si désactivé, l'utilisateur doit cliquer sur le bouton de fermeture pour rejeter l'invite. +- **Activer l'expérience utilisateur One Tap améliorée sur les navigateurs ITP** – Active l'expérience utilisateur Google One Tap améliorée sur les navigateurs avec Intelligent Tracking Prevention (ITP). Consultez [cette documentation](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) pour plus d'informations. -:::caution -Assurez-vous d'ajouter l'origine de votre serveur à la section **Origines JavaScript autorisées** dans la configuration de l'écran de consentement OAuth. Sinon, Google One Tap ne pourra pas être affiché. +:::warning +Assurez-vous d'ajouter votre domaine dans la section **Origines JavaScript autorisées** de la configuration de votre client OAuth. Sinon, Google One Tap ne pourra pas s'afficher. ::: +### Limitations importantes avec Google One Tap \{#important-limitations-with-google-one-tap} + +Si vous activez **Stocker les jetons pour un accès API persistant** en même temps que **Google One Tap**, vous ne recevrez pas automatiquement de jeton d'accès ni les portées demandées. + +La connexion via Google One Tap (contrairement au bouton standard "Se connecter avec Google") **ne** délivre pas de jeton d'accès OAuth. Elle ne retourne qu'un jeton d'identifiant (un JWT signé) qui vérifie l'identité de l'utilisateur, mais ne donne pas accès à l'API. + +Pour accéder aux API Google avec les utilisateurs Google One Tap, vous pouvez utiliser l'API de vérification sociale de Logto pour relancer un flux d'autorisation sociale fédérée après la connexion de l'utilisateur avec Google One Tap. Cela vous permet de demander des portées supplémentaires selon les besoins et de mettre à jour l'ensemble de jetons stockés de l'utilisateur, sans exiger que les portées soient pré-remplies dans le connecteur Google Logto. Cette approche permet une autorisation incrémentielle, de sorte que les utilisateurs ne sont invités à accorder des permissions supplémentaires que lorsque votre application en a réellement besoin. + +En savoir plus sur les [limitations de Google One Tap](https://developers.google.com/identity/gsi/web/guides/overview) dans la documentation officielle. + +## Étape 8 : Tester et publier votre application \{#step-8-test-and-publish-your-app} + +### Pour les applications internes \{#for-internal-apps} + +Si votre type **Audience (Audience)** dans Google est défini sur **Interne**, votre application ne sera disponible qu'aux utilisateurs Google Workspace de votre organisation. Vous pouvez tester avec n'importe quel compte de votre organisation. + +### Pour les applications externes \{#for-external-apps} + +Si votre type **Audience (Audience)** est **Externe** : + +1. **Pendant le développement** : Accédez à **Écran de consentement OAuth > Utilisateurs de test** et ajoutez les adresses e-mail des utilisateurs de test. Seuls ces utilisateurs pourront se connecter avec votre application. +2. **Pour la production** : Cliquez sur **Publier l'application** dans la section écran de consentement OAuth pour la rendre disponible à toute personne disposant d'un compte Google. + :::note -Pour activer Google One Tap sur votre site Web (au-delà de l'expérience de connexion Logto), cette fonctionnalité est en cours de développement. Veuillez rester à l'écoute pour les mises à jour. +Les applications avec des portées sensibles ou restreintes peuvent nécessiter une vérification par Google avant de pouvoir être publiées. Ce processus peut prendre plusieurs semaines. ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index 2a39500f645..ed8a426c842 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -2,10 +2,10 @@ slug: /integrations/oauth2 sidebar_label: OAuth 2.0 (Social) sidebar_custom_props: - description: Le cadre d'autorisation OAuth 2.0 permet à une application tierce d'obtenir un accès limité à un service HTTP. + description: Le cadre d’autorisation OAuth 2.0 permet à une application tierce d’obtenir un accès limité à un service HTTP. logoFilename: 'oauth.svg' tutorial_name: OAuth2 -tutorial_config_name: Application OAuth 2.0 standard +tutorial_config_name: Standard OAuth 2.0 app --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -20,11 +20,21 @@ Le connecteur officiel Logto pour le protocole OAuth 2.0. ## Commencer \{#get-started} -Le connecteur OAuth permet la connexion de Logto à un fournisseur d'identité sociale arbitraire qui prend en charge le protocole OAuth 2.0. +Le connecteur OAuth permet à Logto de se connecter à n'importe quel fournisseur d'identité sociale prenant en charge le protocole OAuth 2.0. Utilisez le connecteur OAuth pour permettre à votre application de : + +- Ajouter des boutons de connexion sociale +- Lier les comptes utilisateurs à des identités sociales +- Synchroniser les informations de profil utilisateur depuis le fournisseur social +- Accéder à des API tierces via le stockage sécurisé des jetons dans le Logto Secret Vault pour des tâches d’automatisation (par exemple, modifier des Google Docs, gérer des événements de calendrier dans votre application) + +Pour configurer ces fonctionnalités d’authentification, créez d’abord un connecteur OAuth 2.0 dans Logto : + +1. Allez dans Console Logto > Connecteur > Connecteur social. +2. Cliquez sur **Ajouter un connecteur social**, sélectionnez **OAuth 2.0**, cliquez sur **Suivant**, puis suivez le tutoriel étape par étape pour finaliser l’intégration. :::note -Le connecteur OAuth est un type spécial de connecteur dans Logto, vous pouvez ajouter quelques connecteurs basés sur le protocole OAuth. +Le connecteur OAuth est un type particulier de connecteur dans Logto, vous pouvez ajouter plusieurs connecteurs basés sur le protocole OAuth. ::: @@ -32,4 +42,4 @@ Le connecteur OAuth est un type spécial de connecteur dans Logto, vous pouvez a ## Référence \{#reference} -Le cadre d'autorisation OAuth 2.0 +Le cadre d’autorisation OAuth 2.0 diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index 6802019b26b..ab9e912a628 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ ## Créez votre application OAuth \{#create-your-oauth-app} -Lorsque vous ouvrez cette page, nous supposons que vous savez déjà quel fournisseur d'identité sociale vous souhaitez connecter. La première chose à faire est de confirmer que le fournisseur d'identité prend en charge le protocole OAuth, qui est une condition préalable pour configurer un connecteur valide. Ensuite, suivez les instructions du fournisseur d'identité pour enregistrer et créer l'application pertinente pour l'autorisation OAuth. +Lorsque vous ouvrez cette page, nous supposons que vous savez déjà quel fournisseur d'identité sociale vous souhaitez connecter. La première chose à faire est de confirmer que le fournisseur d'identité prend en charge le protocole OAuth, ce qui est une condition préalable pour configurer un connecteur valide. Ensuite, suivez les instructions du fournisseur d'identité pour enregistrer et créer l'application correspondante pour l'autorisation OAuth. ## Configurez votre connecteur \{#configure-your-connector} -Nous prenons en charge UNIQUEMENT le type de subvention "Authorization Code" pour des raisons de sécurité et il peut parfaitement s'adapter au scénario de Logto. +Nous prenons UNIQUEMENT en charge le type de flux "Authorization Code" pour des raisons de sécurité, et il s'adapte parfaitement au scénario de Logto. -`clientId` et `clientSecret` peuvent être trouvés sur la page des détails de vos applications OAuth. +`clientId` et `clientSecret` se trouvent sur la page de détails de votre application OAuth. -_clientId_ : L'ID client est un identifiant unique qui identifie l'application cliente lors de l'enregistrement auprès du serveur d'autorisation. Cet ID est utilisé par le serveur d'autorisation pour vérifier l'identité de l'application cliente et pour associer tout jeton d’accès autorisé à cette application cliente spécifique. +_clientId_ : L'identifiant client est un identifiant unique qui identifie l'application cliente lors de l'enregistrement auprès du serveur d'autorisation. Cet identifiant est utilisé par le serveur d'autorisation pour vérifier l'identité de l'application cliente et associer tout jeton d’accès autorisé à cette application cliente spécifique. -_clientSecret_ : Le secret client est une clé confidentielle qui est délivrée à l'application cliente par le serveur d'autorisation lors de l'enregistrement. L'application cliente utilise cette clé secrète pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Le secret client est considéré comme une information confidentielle et doit être gardé en sécurité à tout moment. +_clientSecret_ : Le secret client est une clé confidentielle délivrée à l'application cliente par le serveur d'autorisation lors de l'enregistrement. L'application cliente utilise cette clé secrète pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Le secret client est considéré comme une information confidentielle et doit être conservé en sécurité en tout temps. -_tokenEndpointAuthMethod_ : La méthode d'authentification du point de terminaison de jeton est utilisée par l'application cliente pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Pour découvrir les méthodes prises en charge, consultez le champ `token_endpoint_auth_methods_supported` disponible au point de terminaison de découverte OpenID Connect du fournisseur de services OAuth 2.0, ou référez-vous à la documentation pertinente fournie par le fournisseur de services OAuth 2.0. +_tokenEndpointAuthMethod_ : La méthode d'authentification du point de terminaison du jeton est utilisée par l'application cliente pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Pour découvrir les méthodes prises en charge, consultez le champ `token_endpoint_auth_methods_supported` disponible sur le point de terminaison de découverte OpenID Connect du fournisseur de service OAuth 2.0, ou référez-vous à la documentation pertinente fournie par le fournisseur de service OAuth 2.0. -_clientSecretJwtSigningAlgorithm (Optionnel)_ : Requis uniquement lorsque `tokenEndpointAuthMethod` est `client_secret_jwt`. L'algorithme de signature JWT du secret client est utilisé par l'application cliente pour signer le JWT qui est envoyé au serveur d'autorisation lors de la requête de jeton. +_clientSecretJwtSigningAlgorithm (Optionnel)_ : Nécessaire uniquement lorsque `tokenEndpointAuthMethod` est `client_secret_jwt`. L'algorithme de signature JWT du secret client est utilisé par l'application cliente pour signer le JWT envoyé au serveur d'autorisation lors de la demande de jeton. -_scope_ : Le paramètre de portée est utilisé pour spécifier l'ensemble des ressources et des permissions auxquelles l'application cliente demande l'accès. Le paramètre de portée est généralement défini comme une liste de valeurs séparées par des espaces qui représentent des permissions spécifiques. Par exemple, une valeur de portée de "read write" pourrait indiquer que l'application cliente demande un accès en lecture et écriture aux données d'un utilisateur. +_scope_ : Le paramètre scope est utilisé pour spécifier l'ensemble des ressources et permissions que l'application cliente demande à accéder. Le paramètre scope est généralement défini comme une liste de valeurs séparées par des espaces représentant des permissions spécifiques. Par exemple, une valeur de scope "read write" peut indiquer que l'application cliente demande un accès en lecture et écriture aux données d'un utilisateur. Vous êtes censé trouver `authorizationEndpoint`, `tokenEndpoint` et `userInfoEndpoint` dans la documentation du fournisseur social. _authenticationEndpoint_ : Ce point de terminaison est utilisé pour initier le processus d'authentification. Le processus d'authentification implique généralement que l'utilisateur se connecte et accorde l'autorisation à l'application cliente d'accéder à ses ressources. -_tokenEndpoint_ : Ce point de terminaison est utilisé par l'application cliente pour obtenir un jeton d’accès qui peut être utilisé pour accéder aux ressources demandées. L'application cliente envoie généralement une requête au point de terminaison de jeton avec un type de subvention et un code d'autorisation pour recevoir un jeton d’accès. +_tokenEndpoint_ : Ce point de terminaison est utilisé par l'application cliente pour obtenir un jeton d’accès qui peut être utilisé pour accéder aux ressources demandées. L'application cliente envoie généralement une requête au point de terminaison du jeton avec un type de flux et un code d'autorisation pour recevoir un jeton d’accès. -_userInfoEndpoint_ : Ce point de terminaison est utilisé par l'application cliente pour obtenir des informations supplémentaires sur l'utilisateur, telles que son nom complet, son adresse e-mail ou sa photo de profil. Le point de terminaison des informations utilisateur est généralement accessible après que l'application cliente a obtenu un jeton d’accès du point de terminaison de jeton. +_userInfoEndpoint_ : Ce point de terminaison est utilisé par l'application cliente pour obtenir des informations supplémentaires sur l'utilisateur, telles que son nom complet, son adresse e-mail ou sa photo de profil. Le point de terminaison user info est généralement accessible après que l'application cliente a obtenu un jeton d’accès depuis le point de terminaison du jeton. -Logto fournit également un champ `profileMap` que les utilisateurs peuvent personnaliser pour le mappage des profils des fournisseurs sociaux qui ne sont généralement pas standard. Les clés sont les noms de champs de profil utilisateur standard de Logto et les valeurs correspondantes doivent être les noms de champs des profils sociaux. À l'heure actuelle, Logto ne se préoccupe que de 'id', 'name', 'avatar', 'email' et 'phone' du profil social, seul 'id' est requis et les autres sont des champs optionnels. +Logto fournit également un champ `profileMap` que les utilisateurs peuvent personnaliser pour la correspondance des profils des fournisseurs sociaux, qui ne sont généralement pas standardisés. Les clés sont les noms de champs de profil utilisateur standard de Logto et les valeurs correspondantes doivent être les noms de champs des profils sociaux. À ce stade, Logto ne prend en compte que 'id', 'name', 'avatar', 'email' et 'phone' du profil social, seul 'id' est requis et les autres sont des champs optionnels. -`responseType` et `grantType` peuvent UNIQUEMENT être des valeurs FIXES avec le type de subvention par code d'autorisation, nous les rendons donc optionnels et les valeurs par défaut seront automatiquement remplies. +`responseType` et `grantType` ne peuvent être que des valeurs FIXES avec le flux authorization code, donc nous les rendons optionnels et les valeurs par défaut seront automatiquement renseignées. -Par exemple, vous pouvez trouver [la réponse du profil utilisateur de Google](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) et donc son `profileMap` devrait ressembler à : +Par exemple, vous pouvez trouver [la réponse du profil utilisateur Google](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) et donc son `profileMap` devrait ressembler à ceci : ```json { @@ -41,8 +41,8 @@ Par exemple, vous pouvez trouver [la réponse du profil utilisateur de Google](h :::note -Nous avons fourni une clé `customConfig` OPTIONNELLE pour mettre vos paramètres personnalisés. -Chaque fournisseur d'identité sociale pourrait avoir sa propre variante sur le protocole standard OAuth. Si votre fournisseur d'identité sociale souhaité respecte strictement le protocole standard OAuth, alors vous n'avez pas besoin de vous soucier de `customConfig`. +Nous avons fourni une clé `customConfig` OPTIONNELLE pour y placer vos paramètres personnalisés. +Chaque fournisseur d'identité sociale peut avoir sa propre variante du protocole standard OAuth. Si votre fournisseur d'identité sociale respecte strictement le protocole standard OAuth, alors vous n'avez pas à vous soucier de `customConfig`. ::: @@ -69,3 +69,69 @@ Chaque fournisseur d'identité sociale pourrait avoir sa propre variante sur le | avatar | string | false | avatar | | email | string | false | email | | phone | string | false | phone | + +## Paramètres généraux \{#general-settings} + +Voici quelques paramètres généraux qui ne bloqueront pas la connexion à votre fournisseur d'identité mais peuvent affecter l'expérience d'authentification de l'utilisateur final. + +### Nom et logo du bouton social \{#social-button-name-and-logo} + +Si vous souhaitez afficher un bouton social sur votre page de connexion, vous pouvez définir le **nom** et le **logo** (mode sombre et mode clair) du fournisseur d'identité sociale. Cela aidera les utilisateurs à reconnaître l'option de connexion sociale. + +### Nom du fournisseur d'identité \{#identity-provider-name} + +Chaque connecteur social possède un nom unique de fournisseur d'identité (IdP) pour différencier les identités des utilisateurs. Alors que les connecteurs courants utilisent un nom IdP fixe, les connecteurs personnalisés nécessitent une valeur unique. En savoir plus sur les [noms IdP](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) pour plus de détails. + +### Synchroniser les informations de profil \{#sync-profile-information} + +Dans le connecteur OAuth, vous pouvez définir la politique de synchronisation des informations de profil, telles que les noms d'utilisateur et les avatars. Choisissez parmi : + +- **Synchroniser uniquement lors de l'inscription** : Les informations de profil sont récupérées une seule fois lors de la première connexion de l'utilisateur. +- **Toujours synchroniser à la connexion** : Les informations de profil sont mises à jour à chaque connexion de l'utilisateur. + +### Stocker les jetons pour accéder aux API tierces (Optionnel) \{#store-tokens-to-access-third-party-apis-optional} + +Si vous souhaitez accéder aux API du fournisseur d'identité et effectuer des actions avec l'autorisation de l'utilisateur (que ce soit via la connexion sociale ou la liaison de compte), Logto doit obtenir des portées API spécifiques et stocker les jetons. + +1. Ajoutez les portées requises dans le champ **scope** en suivant les instructions ci-dessus +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur OAuth de Logto. Logto stockera en toute sécurité les jetons d’accès dans le Secret Vault. +3. Pour les fournisseurs d'identité OAuth/OIDC **standards**, la portée `offline_access` doit être incluse pour obtenir un jeton de rafraîchissement, évitant ainsi de demander à nouveau le consentement de l'utilisateur. + +:::warning +Gardez votre secret client en sécurité et ne l'exposez jamais dans le code côté client. En cas de compromission, générez-en un nouveau immédiatement dans les paramètres de l'application de votre fournisseur d'identité. +::: + +## Utiliser le connecteur OAuth \{#utilize-the-oauth-connector} + +Une fois que vous avez créé un connecteur OAuth et que vous l'avez connecté à votre fournisseur d'identité, vous pouvez l'intégrer dans vos flux utilisateurs finaux. Choisissez les options qui correspondent à vos besoins : + +### Activer le bouton de connexion sociale \{#enable-social-sign-in-button} + +1. Dans la Console Logto, allez dans Expérience de connexion > Inscription et connexion. +2. Ajoutez le connecteur OAuth dans la section **Connexion sociale** pour permettre aux utilisateurs de s'authentifier avec votre fournisseur d'identité. + +En savoir plus sur [l'expérience de connexion sociale](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Lier ou délier un compte social \{#link-or-unlink-a-social-account} + +Utilisez l’Account API pour créer un Centre de compte personnalisé dans votre application permettant aux utilisateurs connectés de lier ou délier leurs comptes sociaux. [Suivez le tutoriel Account API](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Il est possible d'activer le connecteur OAuth uniquement pour la liaison de compte et l'accès API, sans l'activer pour la connexion sociale. +::: + +### Accéder aux API du fournisseur d'identité et effectuer des actions \{#access-identity-provider-apis-and-perform-actions} + +Votre application peut récupérer les jetons d’accès stockés dans le Secret Vault pour appeler les API de votre fournisseur d'identité et automatiser des tâches backend. Les capacités spécifiques dépendent de votre fournisseur d'identité et des portées que vous avez demandées. Reportez-vous au guide sur la récupération des jetons stockés pour l'accès API. + +## Gérer l'identité sociale de l'utilisateur \{#manage-user-s-social-identity} + +Après qu'un utilisateur a lié son compte social, les administrateurs peuvent gérer cette connexion dans la Console Logto : + +1. Accédez à Console Logto > Gestion des utilisateurs et ouvrez le profil de l'utilisateur. +2. Sous **Connexions sociales**, localisez l'élément du fournisseur d'identité et cliquez sur **Gérer**. +3. Sur cette page, les administrateurs peuvent gérer la connexion sociale de l'utilisateur, voir toutes les informations de profil accordées et synchronisées depuis son compte social, et vérifier le statut du jeton d’accès. + +:::note +Quelques réponses de jeton d’accès de fournisseur d'identité ne contiennent pas l'information de portée spécifique, donc Logto ne peut pas afficher directement la liste des permissions accordées par l'utilisateur. Cependant, tant que l'utilisateur a consenti aux portées demandées lors de l'autorisation, votre application disposera des permissions correspondantes lors de l'accès à l'API OAuth. +::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index b825bfd9e0b..728f49322e4 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -19,11 +19,21 @@ Le connecteur officiel Logto pour le protocole OpenID Connect (OIDC). ## Commencer \{#get-started} -Le connecteur OIDC permet la connexion de Logto à un fournisseur d'identité sociale arbitraire qui prend en charge le protocole OIDC. +Le connecteur OIDC permet à Logto de se connecter à n'importe quel fournisseur d'identité sociale prenant en charge le protocole OIDC. Utilisez le connecteur OIDC pour permettre à votre application de : + +- Ajouter des boutons de connexion sociale +- Lier les comptes utilisateurs à des identités sociales +- Synchroniser les informations de profil utilisateur depuis le fournisseur social +- Accéder à des API tierces via le stockage sécurisé de jetons dans le Logto Secret Vault pour des tâches d'automatisation (par exemple, modifier des Google Docs, gérer des événements de calendrier dans votre application) + +Pour configurer ces fonctionnalités d'authentification, créez d'abord un connecteur OIDC dans Logto : + +1. Allez dans Console Logto > Connecteur > Connecteur social. +2. Cliquez sur **Ajouter un connecteur social**, sélectionnez **OIDC**, cliquez sur **Suivant**, puis suivez le tutoriel étape par étape pour finaliser l'intégration. :::note -Le connecteur OIDC est un type spécial de connecteur dans Logto, vous pouvez ajouter quelques connecteurs basés sur OIDC. +Le connecteur OIDC est un type particulier de connecteur dans Logto, vous pouvez ajouter plusieurs connecteurs basés sur le protocole OIDC. ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index 430fe69f901..f7a6b894827 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,85 +1,151 @@ ## Créez votre application OIDC \{#create-your-oidc-app} -Lorsque vous ouvrez cette page, nous supposons que vous savez déjà quel fournisseur d'identité sociale vous souhaitez connecter. La première chose à faire est de confirmer que le fournisseur d'identité prend en charge le protocole OIDC, ce qui est une condition préalable pour configurer un connecteur valide. Ensuite, suivez les instructions du fournisseur d'identité pour enregistrer et créer l'application pertinente pour l'autorisation OIDC. +Lorsque vous ouvrez cette page, nous supposons que vous savez déjà quel fournisseur d'identité sociale vous souhaitez connecter. La première chose à faire est de confirmer que le fournisseur d'identité prend en charge le protocole OIDC, ce qui est une condition préalable pour configurer un connecteur valide. Ensuite, suivez les instructions du fournisseur d'identité pour enregistrer et créer l'application correspondante pour l'autorisation OIDC. ## Configurez votre connecteur \{#configure-your-connector} -Nous prenons en charge UNIQUEMENT le type de subvention "Authorization Code" pour des raisons de sécurité, et cela s'adapte parfaitement au scénario de Logto. +Nous prenons UNIQUEMENT en charge le type de flux "Authorization Code" pour des raisons de sécurité, et il s'adapte parfaitement au scénario de Logto. -`clientId` et `clientSecret` peuvent être trouvés sur la page des détails de vos applications OIDC. +`clientId` et `clientSecret` peuvent être trouvés sur la page de détails de votre application OIDC. -_clientId_ : L'ID client est un identifiant unique qui identifie l'application cliente lors de l'enregistrement auprès du serveur d'autorisation. Cet ID est utilisé par le serveur d'autorisation pour vérifier l'identité de l'application cliente et pour associer tout jeton d’accès autorisé à cette application cliente spécifique. +_clientId_ : L'identifiant client est un identifiant unique qui identifie l'application cliente lors de l'enregistrement auprès du serveur d'autorisation. Cet identifiant est utilisé par le serveur d'autorisation pour vérifier l'identité de l'application cliente et pour associer tout jeton d’accès autorisé à cette application cliente spécifique. -_clientSecret_ : Le secret client est une clé confidentielle qui est délivrée à l'application cliente par le serveur d'autorisation lors de l'enregistrement. L'application cliente utilise cette clé secrète pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Le secret client est considéré comme une information confidentielle et doit être gardé en sécurité à tout moment. +_clientSecret_ : Le secret client est une clé confidentielle délivrée à l'application cliente par le serveur d'autorisation lors de l'enregistrement. L'application cliente utilise cette clé secrète pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Le secret client est considéré comme une information confidentielle et doit être conservé en sécurité à tout moment. -_tokenEndpointAuthMethod_ : La méthode d'authentification du point de terminaison de jeton est utilisée par l'application cliente pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Pour découvrir les méthodes prises en charge, consultez le champ `token_endpoint_auth_methods_supported` disponible au point de terminaison de découverte OpenID Connect du fournisseur de services OAuth 2.0, ou référez-vous à la documentation pertinente fournie par le fournisseur de services OAuth 2.0. +_tokenEndpointAuthMethod_ : La méthode d'authentification du point de terminaison de jeton est utilisée par l'application cliente pour s'authentifier auprès du serveur d'autorisation lors de la demande de jetons d’accès. Pour découvrir les méthodes prises en charge, consultez le champ `token_endpoint_auth_methods_supported` disponible sur le point de terminaison de découverte OpenID Connect du fournisseur de service OAuth 2.0, ou référez-vous à la documentation pertinente fournie par le fournisseur de service OAuth 2.0. -_clientSecretJwtSigningAlgorithm (Optionnel)_ : Nécessaire uniquement lorsque `tokenEndpointAuthMethod` est `client_secret_jwt`. L'algorithme de signature JWT du secret client est utilisé par l'application cliente pour signer le JWT qui est envoyé au serveur d'autorisation lors de la demande de jeton. +_clientSecretJwtSigningAlgorithm (Optionnel)_ : Nécessaire uniquement lorsque `tokenEndpointAuthMethod` est `client_secret_jwt`. L'algorithme de signature JWT du secret client est utilisé par l'application cliente pour signer le JWT envoyé au serveur d'autorisation lors de la demande de jeton. -_scope_ : Le paramètre de portée est utilisé pour spécifier l'ensemble des ressources et des permissions auxquelles l'application cliente demande l'accès. Le paramètre de portée est généralement défini comme une liste de valeurs séparées par des espaces qui représentent des permissions spécifiques. Par exemple, une valeur de portée de "read write" pourrait indiquer que l'application cliente demande un accès en lecture et en écriture aux données d'un utilisateur. +_scope_ : Le paramètre scope est utilisé pour spécifier l'ensemble des ressources et permissions que l'application cliente demande à accéder. Le paramètre scope est généralement défini comme une liste de valeurs séparées par des espaces représentant des permissions spécifiques. Par exemple, une valeur de scope "read write" peut indiquer que l'application cliente demande un accès en lecture et en écriture aux données d'un utilisateur. -Vous êtes censé trouver `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` et `issuer` comme informations de configuration du fournisseur OpenID. Ils devraient être disponibles dans la documentation du fournisseur social. +Vous devez trouver `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` et `issuer` comme informations de configuration du fournisseur OpenID. Elles devraient être disponibles dans la documentation du fournisseur social. _authenticationEndpoint_ : Ce point de terminaison est utilisé pour initier le processus d'authentification. Le processus d'authentification implique généralement que l'utilisateur se connecte et accorde l'autorisation à l'application cliente d'accéder à ses ressources. -_tokenEndpoint_ : Ce point de terminaison est utilisé par l'application cliente pour obtenir un jeton d’identifiant qui peut être utilisé pour accéder aux ressources demandées. L'application cliente envoie généralement une demande au point de terminaison de jeton avec un type de subvention et un code d'autorisation pour recevoir un jeton d’identifiant. +_tokenEndpoint_ : Ce point de terminaison est utilisé par l'application cliente pour obtenir un jeton d’identifiant qui peut être utilisé pour accéder aux ressources demandées. L'application cliente envoie généralement une demande au point de terminaison de jeton avec un type de flux et un code d'autorisation pour recevoir un jeton d’identifiant. -_jwksUri_ : C'est l'URL du point de terminaison où l'ensemble de clés Web JSON (JWKS) du fournisseur d'identité sociale (IdP en abrégé) peut être obtenu. Le JWKS est un ensemble de clés cryptographiques que l'IdP utilise pour signer et vérifier les JSON Web Tokens (JWT) qui sont émis lors du processus d'authentification. Le `jwksUri` est utilisé par la partie de confiance (RP) pour obtenir les clés publiques utilisées par l'IdP pour signer les JWT, afin que la RP puisse vérifier l'authenticité et l'intégrité des JWT reçus de l'IdP. +_jwksUri_ : Il s'agit de l'URL où l'ensemble de clés Web JSON (JWKS) du fournisseur d'identité sociale (IdP) peut être obtenu. Le JWKS est un ensemble de clés cryptographiques que l'IdP utilise pour signer et vérifier les JSON Web Tokens (JWT) émis lors du processus d'authentification. Le `jwksUri` est utilisé par la partie de confiance (RP) pour obtenir les clés publiques utilisées par l'IdP pour signer les JWT, afin que la RP puisse vérifier l'authenticité et l'intégrité des JWT reçus de l'IdP. -_issuer_ : C'est l'identifiant unique de l'IdP qui est utilisé par la RP pour vérifier les JWT reçus de l'IdP. Il est inclus dans les JWT en tant que revendication `iss` [claim](https://www.rfc-editor.org/rfc/rfc7519#section-4) (le jeton d’identifiant est toujours un JWT). La valeur de l'émetteur doit correspondre à l'URL du serveur d'autorisation de l'IdP, et elle doit être une URI que la RP considère comme fiable. Lorsque la RP reçoit un JWT, elle vérifie la revendication `iss` pour s'assurer qu'il a été émis par un IdP de confiance, et que le JWT est destiné à être utilisé avec la RP. +_issuer_ : Il s'agit de l'identifiant unique de l'IdP utilisé par la RP pour vérifier les JWT reçus de l'IdP. Il est inclus dans les JWT comme [revendication (Claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4) `iss` (le jeton d’identifiant est toujours un JWT). La valeur de l'émetteur doit correspondre à l'URL du serveur d'autorisation de l'IdP, et il doit s'agir d'un URI auquel la RP fait confiance. Lorsque la RP reçoit un JWT, elle vérifie la revendication `iss` pour s'assurer qu'il a été émis par un IdP de confiance, et que le JWT est destiné à être utilisé avec la RP. -Ensemble, `jwksUri` et `issuer` fournissent un mécanisme sécurisé pour que la RP vérifie l'identité de l'utilisateur final lors du processus d'authentification. En utilisant les clés publiques obtenues à partir du `jwksUri`, la RP peut vérifier l'authenticité et l'intégrité des JWT émis par l'IdP. La valeur de l'émetteur garantit que la RP n'accepte que les JWT qui ont été émis par un IdP de confiance, et que les JWT sont destinés à être utilisés avec la RP. +Ensemble, `jwksUri` et `issuer` fournissent un mécanisme sécurisé permettant à la RP de vérifier l'identité de l'utilisateur final lors du processus d'authentification. En utilisant les clés publiques obtenues à partir du `jwksUri`, la RP peut vérifier l'authenticité et l'intégrité des JWT émis par l'IdP. La valeur de l'émetteur garantit que la RP n'accepte que les JWT émis par un IdP de confiance, et que les JWT sont destinés à être utilisés avec la RP. -Étant donné qu'une requête d’authentification est toujours requise, un `authRequestOptionalConfig` est fourni pour regrouper toutes les configurations optionnelles, vous pouvez trouver des détails sur [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Vous pouvez également constater que `nonce` est absent de cette configuration. Étant donné que `nonce` doit être identique pour chaque requête, nous avons placé la génération de `nonce` dans l'implémentation du code. Donc, ne vous inquiétez pas ! Les `jwksUri` et `issuer` mentionnés précédemment sont également inclus dans `idTokenVerificationConfig`. +Puisqu'une requête d’authentification (Authentication request) est toujours requise, un `authRequestOptionalConfig` est fourni pour regrouper toutes les configurations optionnelles. Vous pouvez trouver les détails sur [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Vous remarquerez peut-être que `nonce` est absent de cette configuration. Comme `nonce` doit être identique pour chaque requête, nous avons placé la génération de `nonce` dans l'implémentation du code. Donc, pas d'inquiétude ! Les `jwksUri` et `issuer` mentionnés précédemment sont également inclus dans `idTokenVerificationConfig`. -Vous vous demandez peut-être pourquoi un protocole OIDC standard prend en charge à la fois les flux implicites et hybrides, alors que le connecteur Logto ne prend en charge que le flux d'autorisation. Il a été déterminé que les flux implicites et hybrides sont moins sécurisés que le flux d'autorisation. En raison de l'accent mis par Logto sur la sécurité, il ne prend en charge que le flux d'autorisation pour offrir le plus haut niveau de sécurité à ses utilisateurs, malgré sa nature légèrement moins pratique. +Vous vous demandez peut-être pourquoi un protocole OIDC standard prend en charge à la fois les flux implicite et hybride, alors que le connecteur Logto ne prend en charge que le flux d'autorisation. Il a été déterminé que les flux implicite et hybride sont moins sécurisés que le flux d'autorisation. En raison de l'accent mis par Logto sur la sécurité, seul le flux d'autorisation est pris en charge pour offrir le plus haut niveau de sécurité à ses utilisateurs, malgré une commodité légèrement moindre. -`responseType` et `grantType` peuvent UNIQUEMENT être des valeurs FIXES avec le flux "Authorization Code", nous les rendons donc optionnels et les valeurs par défaut seront automatiquement remplies. +`responseType` et `grantType` ne peuvent être que des valeurs FIXES avec le flux "Authorization Code", nous les rendons donc optionnels et les valeurs par défaut seront automatiquement renseignées. :::note -Pour tous les types de flux, nous avons fourni une clé `customConfig` OPTIONNELLE pour placer vos paramètres personnalisés. -Chaque fournisseur d'identité sociale pourrait avoir sa propre variante du protocole standard OIDC. Si votre fournisseur d'identité sociale souhaité respecte strictement le protocole standard OIDC, alors vous n'avez pas besoin de vous soucier de `customConfig`. +Pour tous les types de flux, nous avons fourni une clé OPTIONNELLE `customConfig` pour y placer vos paramètres personnalisés. +Chaque fournisseur d'identité sociale peut avoir sa propre variante du protocole standard OIDC. Si votre fournisseur d'identité sociale respecte strictement le protocole standard OIDC, vous n'avez pas à vous soucier de `customConfig`. ::: ## Types de configuration \{#config-types} -| Nom | Type | Requis | -| ------------------------- | ------------------------- | ------ | -| scope | string | Vrai | -| clientId | string | Vrai | -| clientSecret | string | Vrai | -| authorizationEndpoint | string | Vrai | -| tokenEndpoint | string | Vrai | -| idTokenVerificationConfig | IdTokenVerificationConfig | Vrai | -| authRequestOptionalConfig | AuthRequestOptionalConfig | Faux | -| customConfig | Record\ | Faux | - -| Propriétés AuthRequestOptionalConfig | Type | Requis | -| ------------------------------------ | ------ | ------ | -| responseType | string | Faux | -| tokenEndpoint | string | Faux | -| responseMode | string | Faux | -| display | string | Faux | -| prompt | string | Faux | -| maxAge | string | Faux | -| uiLocales | string | Faux | -| idTokenHint | string | Faux | -| loginHint | string | Faux | -| acrValues | string | Faux | - -| Propriétés IdTokenVerificationConfig | Type | Requis | -| ------------------------------------ | ---------------------------------- | ------ | -| jwksUri | string | Vrai | -| issuer | string \| string[] | Faux | -| audience | string \| string[] | Faux | -| algorithms | string[] | Faux | -| clockTolerance | string \| number | Faux | -| crit | Record\ | Faux | -| currentDate | Date | Faux | -| maxTokenAge | string \| number | Faux | -| subject | string | Faux | -| typ | string | Faux | +| Nom | Type | Obligatoire | +| ------------------------- | ------------------------- | ----------- | +| scope | string | Oui | +| clientId | string | Oui | +| clientSecret | string | Oui | +| authorizationEndpoint | string | Oui | +| tokenEndpoint | string | Oui | +| idTokenVerificationConfig | IdTokenVerificationConfig | Oui | +| authRequestOptionalConfig | AuthRequestOptionalConfig | Non | +| customConfig | Record\ | Non | + +| Propriétés AuthRequestOptionalConfig | Type | Obligatoire | +| ------------------------------------ | ------ | ----------- | +| responseType | string | Non | +| tokenEndpoint | string | Non | +| responseMode | string | Non | +| display | string | Non | +| prompt | string | Non | +| maxAge | string | Non | +| uiLocales | string | Non | +| idTokenHint | string | Non | +| loginHint | string | Non | +| acrValues | string | Non | + +| Propriétés IdTokenVerificationConfig | Type | Obligatoire | +| ------------------------------------ | ---------------------------------- | ----------- | +| jwksUri | string | Oui | +| issuer | string \| string[] | Non | +| audience | string \| string[] | Non | +| algorithms | string[] | Non | +| clockTolerance | string \| number | Non | +| crit | Record\ | Non | +| currentDate | Date | Non | +| maxTokenAge | string \| number | Non | +| subject | string | Non | +| typ | string | Non | Voir [ici](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) pour plus de détails sur `IdTokenVerificationConfig`. + +## Paramètres généraux \{#general-settings} + +Voici quelques paramètres généraux qui ne bloqueront pas la connexion à votre fournisseur d'identité mais peuvent affecter l'expérience d'authentification de l'utilisateur final. + +### Nom et logo du bouton social \{#social-button-name-and-logo} + +Si vous souhaitez afficher un bouton social sur votre page de connexion, vous pouvez définir le **nom** et le **logo** (mode sombre et mode clair) du fournisseur d'identité sociale. Cela aidera les utilisateurs à reconnaître l'option de connexion sociale. + +### Nom du fournisseur d'identité \{#identity-provider-name} + +Chaque connecteur social possède un nom unique de Fournisseur d’identité (IdP) pour différencier les identités utilisateur. Alors que les connecteurs courants utilisent un nom d'IdP fixe, les connecteurs personnalisés nécessitent une valeur unique. En savoir plus sur les [noms d’IdP](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) pour plus de détails. + +### Synchroniser les informations de profil \{#sync-profile-information} + +Dans le connecteur OIDC, vous pouvez définir la politique de synchronisation des informations de profil, telles que les noms d'utilisateur et les avatars. Choisissez parmi : + +- **Synchroniser uniquement lors de l'inscription** : Les informations de profil sont récupérées une seule fois lors de la première connexion de l'utilisateur. +- **Toujours synchroniser à la connexion** : Les informations de profil sont mises à jour à chaque connexion de l'utilisateur. + +### Stocker les jetons pour accéder aux API tierces (Optionnel) \{#store-tokens-to-access-third-party-apis-optional} + +Si vous souhaitez accéder aux API du fournisseur d'identité et effectuer des actions avec l'autorisation de l'utilisateur (que ce soit via la connexion sociale ou la liaison de compte), Logto doit obtenir des portées API spécifiques et stocker les jetons. + +1. Ajoutez les portées requises dans le champ **scope** en suivant les instructions ci-dessus +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur OIDC de Logto. Logto stockera en toute sécurité les jetons d’accès dans le Secret Vault. +3. Pour les fournisseurs d'identité OAuth/OIDC **standards**, la portée `offline_access` doit être incluse pour obtenir un jeton de rafraîchissement, évitant ainsi les demandes répétées de consentement utilisateur. + +:::warning +Gardez votre secret client en sécurité et ne l'exposez jamais dans le code côté client. En cas de compromission, générez-en un nouveau immédiatement dans les paramètres de l'application de votre fournisseur d'identité. +::: + +## Utiliser le connecteur OIDC \{#utilize-the-oidc-connector} + +Une fois que vous avez créé un connecteur OIDC et que vous l'avez connecté à votre fournisseur d'identité, vous pouvez l'intégrer dans vos flux utilisateur finaux. Choisissez les options qui correspondent à vos besoins : + +### Activer le bouton de connexion sociale \{#enable-social-sign-in-button} + +1. Dans Logto Console, allez dans Expérience de connexion > Inscription et connexion. +2. Ajoutez le connecteur OIDC dans la section **Connexion sociale** pour permettre aux utilisateurs de s'authentifier avec votre fournisseur d'identité. + +En savoir plus sur [l'expérience de connexion sociale](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Lier ou délier un compte social \{#link-or-unlink-a-social-account} + +Utilisez l’Account API pour créer un Centre de compte personnalisé dans votre application permettant aux utilisateurs connectés de lier ou délier leurs comptes sociaux. [Suivez le tutoriel Account API](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Il est possible d'activer le connecteur OIDC uniquement pour la liaison de compte et l'accès API, sans l'activer pour la connexion sociale. +::: + +### Accéder aux API du fournisseur d'identité et effectuer des actions \{#access-identity-provider-apis-and-perform-actions} + +Votre application peut récupérer les jetons d’accès stockés dans le Secret Vault pour appeler les API de votre fournisseur d'identité et automatiser des tâches backend. Les capacités spécifiques dépendent de votre fournisseur d'identité et des portées que vous avez demandées. Reportez-vous au guide sur la récupération des jetons stockés pour l'accès API. + +## Gérer l'identité sociale de l'utilisateur \{#manage-user-s-social-identity} + +Après qu'un utilisateur a lié son compte social, les administrateurs peuvent gérer cette connexion dans la Logto Console : + +1. Accédez à Logto console > Gestion des utilisateurs et ouvrez le profil de l'utilisateur. +2. Sous **Connexions sociales**, localisez l'élément du fournisseur d'identité et cliquez sur **Gérer**. +3. Sur cette page, les administrateurs peuvent gérer la connexion sociale de l'utilisateur, voir toutes les informations de profil accordées et synchronisées depuis son compte social, et vérifier le statut du jeton d’accès. + +:::note +Quelques réponses de jeton d’accès du fournisseur d'identité ne contiennent pas l'information de scope spécifique, donc Logto ne peut pas afficher directement la liste des permissions accordées par l'utilisateur. Cependant, tant que l'utilisateur a consenti aux portées demandées lors de l'autorisation, votre application disposera des permissions correspondantes lors de l'accès à l'API OIDC. +::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index 8ec01fb559a..af471e6af0d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: Gestion unifiée et sécurisée de l'accès des utilisateurs au sein de l'écosystème Google. + description: Gestion unifiée et sécurisée de l’accès des utilisateurs au sein de l’écosystème Google. (Unified and secure management of user access within the Google ecosystem.) logoFilename: 'google.svg' tutorial_name: Google Workspace enterprise SSO tutorial_config_name: Google Cloud Platform @@ -16,10 +16,11 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -# Configurer l’authentification unique avec Google Workspace +# Configurer l’authentification unique avec Google Workspace (Set up Single Sign-On with Google Workspace) -Avec un minimum d'efforts de configuration, ce connecteur permet l'intégration avec Microsoft Entra ID pour le SSO d’entreprise. +Avec un minimum de configuration, ce connecteur permet l’intégration avec Microsoft Entra ID pour le SSO d’entreprise. @@ -31,7 +32,7 @@ Avec un minimum d'efforts de configuration, ce connecteur permet l'intégration -## Étape 3 : Créer une nouvelle accréditation OAuth \{#step-3-create-a-new-oauth-credential} +## Étape 3 : Créer de nouvelles informations d’identification OAuth \{#step-3-create-a-new-oauth-credential} @@ -39,10 +40,14 @@ Avec un minimum d'efforts de configuration, ce connecteur permet l'intégration -## Étape 5 : Portées supplémentaires (Optionnel) \{#step-5-additional-scopes-optional} +## Étape 5 : Portées supplémentaires (optionnel) \{#step-5-additional-scopes-optional} -## Étape 6 : Définir les domaines de messagerie et activer le connecteur SSO \{#step-6-set-email-domains-and-enable-the-sso-connector} +## Étape 6 : Stocker les jetons pour accéder aux API Google (optionnel) \{#step-6-store-tokens-to-access-google-apis-optional} + +## Étape 7 : Définir les domaines e-mail et activer le connecteur SSO \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index 4989027e2da..6dd3bdcf0e4 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,6 +4,7 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; ### Étape 1 : Créer un nouveau projet sur Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} @@ -13,11 +14,11 @@ import Step6 from './_step-6.mdx'; -### Étape 3 : Créer une nouvelle accréditation OAuth \{#step-3-create-a-new-oauth-credential} +### Étape 3 : Créer de nouvelles informations d’identification OAuth \{#step-3-create-a-new-oauth-credential} -### Étape 4 : Configurer le connecteur Logto avec les identifiants du client \{#step-4-set-up-logto-connector-with-the-client-credentials} +### Étape 4 : Configurer le connecteur Logto avec les identifiants client \{#step-4-set-up-logto-connector-with-the-client-credentials} @@ -25,6 +26,10 @@ import Step6 from './_step-6.mdx'; -### Étape 6 : Définir les domaines de messagerie et activer le connecteur SSO \{#step-6-set-email-domains-and-enable-the-sso-connector} +### Étape 6 : Stocker les jetons pour accéder aux API Google (Optionnel) \{#step-6-store-tokens-to-access-google-apis-optional} + +### Étape 7 : Définir les domaines e-mail et activer le connecteur SSO \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index 562b7ecdb14..3d894bd0220 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -Utilisez le champ `Scope` pour ajouter des portées supplémentaires à votre requête OAuth. Cela vous permettra de demander plus d'informations au serveur OAuth de Google. Veuillez vous référer à la documentation des [Portées OAuth de Google](https://developers.google.com/identity/protocols/oauth2/scopes) pour plus d'informations. +Les portées (Scopes) définissent les permissions que votre application demande aux utilisateurs et contrôlent à quelles données votre application peut accéder dans leurs comptes Google Workspace. La demande de permissions Google nécessite une configuration des deux côtés : -Indépendamment des paramètres de portée personnalisés, Logto enverra toujours les portées `openid`, `profile` et `email` au fournisseur d’identité (IdP). Cela garantit que Logto peut récupérer correctement les informations d'identité de l'utilisateur et l'adresse e-mail. +**Dans la Google Cloud Console :** + +1. Accédez à **APIs & Services > Écran de consentement OAuth > Portées (Scopes)**. +2. Cliquez sur **Ajouter ou supprimer des portées** et sélectionnez uniquement les portées dont votre application a besoin : + - Authentification (obligatoire) : + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - Accès à l’API (optionnel) : Ajoutez toutes les portées supplémentaires nécessaires pour votre application (par exemple, Drive, Calendar, YouTube). Parcourez la [bibliothèque d’API Google](https://console.cloud.google.com/apis/library) pour trouver les services disponibles. Si votre application a besoin d’accéder à des API Google au-delà des permissions de base, activez d’abord les API spécifiques que votre application utilisera (par exemple, Google Drive API, Gmail API, Calendar API) dans la bibliothèque d’API Google. +3. Cliquez sur **Mettre à jour** pour confirmer la sélection. +4. Cliquez sur **Enregistrer et continuer** pour appliquer les modifications. + +**Dans le connecteur Logto Google Workspace :** + +1. Logto inclut automatiquement les portées `openid`, `profile` et `email` pour récupérer les informations d'identité de base de l'utilisateur. Vous pouvez laisser le champ `Scopes` vide si vous n'avez besoin que des informations de base sur l'utilisateur. +2. Ajoutez des portées supplémentaires (séparées par des espaces) dans le champ `Scopes` pour demander plus de données à Google. Utilisez les URLs complètes des portées, par exemple : `https://www.googleapis.com/auth/calendar.readonly` + +:::tip +Si votre application demande ces portées pour accéder à l’API Google et effectuer des actions, assurez-vous d’activer **Stocker les jetons pour un accès API persistant** dans le connecteur Logto Google. Voir la section suivante pour plus de détails. +::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index 9f10016b6c7..92845b1eae7 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -Fournissez les `domaines de messagerie` de votre organisation dans l'onglet `Expérience SSO` du connecteur Logto. Cela activera le connecteur SSO comme méthode d'authentification pour ces utilisateurs. +Si vous souhaitez accéder aux [API Google](https://console.cloud.google.com/apis/library) et effectuer des actions avec l'autorisation de l'utilisateur, Logto doit obtenir des portées API spécifiques et stocker les jetons. -Les utilisateurs ayant des adresses e-mail dans les domaines spécifiés seront redirigés pour utiliser votre connecteur SSO comme seule méthode d'authentification. +1. Ajoutez les portées requises dans la configuration de l'écran de consentement OAuth de votre Google Cloud Console et dans le connecteur Google de Logto. +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur Google de Logto. Logto stockera de manière sécurisée les jetons d’accès Google et les jetons de rafraîchissement dans le Secret Vault. +3. Pour garantir que les jetons de rafraîchissement sont renvoyés, configurez votre connecteur Google Logto pour activer **l’accès hors ligne**. -Pour plus d'informations sur le connecteur SSO Google Workspace, veuillez consulter [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). +:::warning +Vous n'avez pas besoin d’ajouter `offline_access` dans le champ `Scope` de Logto — le faire peut entraîner une erreur. Google utilise automatiquement `access_type=offline` lorsque l’accès hors ligne est activé. +::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..6740fd84da6 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +Fournissez les `domaines e-mail` de votre organisation dans l’onglet `Expérience SSO` du connecteur Logto. Cela activera le connecteur SSO comme méthode d’authentification pour ces utilisateurs. + +Les utilisateurs ayant des adresses e-mail dans les domaines spécifiés seront redirigés pour utiliser votre connecteur SSO comme seule méthode d’authentification. + +Pour plus d’informations sur le connecteur Google Workspace SSO, veuillez consulter [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 4878f5c074f..b3cd4c9c8a1 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -5,7 +5,7 @@ sidebar_custom_props: description: Protocole moderne basé sur OAuth 2.0 pour la vérification d'identité dans les applications web et mobiles. logoFilename: 'oidc.svg' tutorial_name: OIDC enterprise SSO -tutorial_config_name: Application OIDC sur votre IdP +tutorial_config_name: OIDC application on your IdP --- import GuideTip from '../../fragments/_sso_guide_tip.mdx'; @@ -13,10 +13,12 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; # Configurer l’authentification unique avec OpenID Connect (OIDC) -Avec un minimum d'efforts de configuration, ce connecteur permet l'intégration avec n'importe quel fournisseur d'identité (IdP) basé sur OIDC. +Avec un minimum de configuration, ce connecteur permet l’intégration avec n’importe quel fournisseur d’identité (IdP) basé sur OIDC. @@ -28,6 +30,14 @@ Avec un minimum d'efforts de configuration, ce connecteur permet l'intégration -## Étape 3 : Définir les domaines de messagerie et activer le connecteur SSO \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Étape 3 : Configurer les portées (Optionnel) \{#step-3-configure-scopes-optional} + +## Étape 4 : Stocker les jetons pour accéder aux API tierces (Optionnel) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Étape 5 : Définir les domaines e-mail et activer le connecteur SSO \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index b3fe75bf029..b7e41edb468 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,15 +1,25 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; ### Étape 1 : Créer une application OIDC sur votre fournisseur d’identité (IdP) \{#step-1-create-an-oidc-application-on-your-idp} -### Étape 2 : Configurer l'authentification unique OIDC sur Logto \{#step-2-configure-oidc-sso-on-logto} +### Étape 2 : Configurer l’authentification unique OIDC sur Logto \{#step-2-configure-oidc-sso-on-logto} -### Étape 3 : Définir les domaines de messagerie et activer le connecteur SSO \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Étape 3 : Configurer les portées (Scopes) (Optionnel) \{#step-3-configure-scopes-optional} + +## Étape 4 : Stocker les jetons pour accéder aux API tierces (Optionnel) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Étape 5 : Définir les domaines e-mail et activer le connecteur SSO \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index 09b1a4bca0f..efa31808581 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -Après avoir créé avec succès une application OIDC du côté du fournisseur d'identité (IdP), vous devrez fournir les configurations de l'IdP à Logto. Accédez à l'onglet `Connection` et remplissez les configurations suivantes : +Après avoir créé avec succès une application OIDC du côté du fournisseur d’identité (IdP), vous devrez fournir les configurations de l’IdP à Logto. Accédez à l’onglet `Connection` et renseignez les configurations suivantes : -- **Client ID** : Un identifiant unique attribué à votre application OIDC par l'IdP. Cet identifiant est utilisé par Logto pour identifier et authentifier l'application pendant le flux OIDC. -- **Client Secret** : Un secret confidentiel partagé entre Logto et l'IdP. Ce secret est utilisé pour authentifier l'application OIDC et sécuriser la communication entre Logto et l'IdP. -- **Émetteur (Issuer)** : L'URL de l'émetteur, un identifiant unique pour l'IdP, spécifiant l'emplacement où le fournisseur d'identité OIDC peut être trouvé. C'est une partie cruciale de la configuration OIDC car elle aide Logto à découvrir les points de terminaison nécessaires. - Pour faciliter le processus de configuration, Logto récupérera automatiquement les points de terminaison et configurations OIDC requis. Cela se fait en utilisant l'émetteur que vous avez fourni et en effectuant un appel aux points de terminaison de découverte OIDC de l'IdP. Il est impératif de s'assurer que le point de terminaison de l'émetteur est valide et correctement configuré pour permettre à Logto de récupérer correctement les informations requises. - Après une requête de récupération réussie, vous devriez pouvoir voir les configurations de l'IdP analysées sous la section des émetteurs. -- **Portée (Scope)** : Une liste de chaînes séparées par des espaces définissant les permissions ou niveaux d'accès souhaités demandés par Logto pendant le processus d'authentification OIDC. Le paramètre de portée vous permet de spécifier quelles informations et accès Logto demande à l'IdP. - Le paramètre de portée est optionnel. Indépendamment des paramètres de portée personnalisés, Logto enverra toujours les portées `openid`, `profile` et `email` à l'IdP. - Cela garantit que Logto peut récupérer correctement les informations d'identité de l'utilisateur et l'adresse e-mail de l'IdP. Vous pouvez ajouter des portées supplémentaires au paramètre de portée pour demander plus d'informations à l'IdP. +- **Client ID** : Un identifiant unique attribué à votre application OIDC par l’IdP. Cet identifiant est utilisé par Logto pour identifier et authentifier l’application lors du flux OIDC. +- **Client Secret** : Un secret confidentiel partagé entre Logto et l’IdP. Ce secret est utilisé pour authentifier l’application OIDC et sécuriser la communication entre Logto et l’IdP. +- **Émetteur (Issuer)** : L’URL de l’émetteur, un identifiant unique pour l’IdP, spécifiant l’emplacement où le fournisseur d’identité OIDC peut être trouvé. Il s’agit d’une partie cruciale de la configuration OIDC car elle permet à Logto de découvrir les points de terminaison nécessaires. + Pour faciliter le processus de configuration, Logto récupérera automatiquement les points de terminaison et configurations OIDC requis. Cela se fait en utilisant l’émetteur que vous avez fourni et en effectuant un appel aux points de terminaison de découverte OIDC de l’IdP. Il est impératif de s’assurer que le point de terminaison de l’émetteur est valide et correctement configuré afin de permettre à Logto de récupérer correctement les informations nécessaires. + Après une requête de récupération réussie, vous devriez pouvoir voir les configurations IdP analysées dans la section des émetteurs. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index c40dafd0b3c..778672cf283 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -Fournissez les `domaines de messagerie` de votre organisation dans l'onglet `Expérience SSO` du connecteur Logto. Cela activera le connecteur SSO comme méthode d'authentification pour ces utilisateurs. +Les portées (Scopes) définissent les permissions que votre application demande aux utilisateurs et contrôlent à quelles données votre application peut accéder depuis leurs comptes d’entreprise. -Les utilisateurs ayant des adresses e-mail dans les domaines spécifiés seront redirigés pour utiliser votre connecteur SSO comme seule méthode d'authentification. +La configuration des portées nécessite une configuration des deux côtés : + +1. **Votre fournisseur d’identité (IdP)** : Configurez quelles permissions sont autorisées pour l’autorisation dans la console de votre IdP + - Certains IdP activent toutes les portées publiques par défaut (aucune action requise) + - D’autres exigent que vous accordiez explicitement les permissions +2. **Connecteur d’entreprise Logto** : Spécifiez quelles portées demander lors de l’authentification dans les paramètres du connecteur OIDC d’entreprise Logto > champ `Scopes`. + - Logto inclut toujours les portées `openid`, `profile` et `email` pour récupérer les informations d’identité de base de l’utilisateur, indépendamment de vos paramètres de portées personnalisées. + - Vous pouvez ajouter des portées supplémentaires (séparées par des espaces) pour demander plus d’informations au IdP. + +:::tip +Si votre application doit accéder à des API en utilisant ces portées, assurez-vous d’activer **Stocker les jetons pour un accès API persistant** dans votre connecteur d’entreprise Logto. Voir la section suivante pour plus de détails. +::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..182d101640a --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +Si vous souhaitez accéder aux API du fournisseur d’identité (Identity Provider) et effectuer des actions avec l’autorisation de l’utilisateur, Logto doit obtenir des portées API (Scopes) spécifiques et stocker les jetons. + +1. Ajoutez les portées requises dans le champ **scope** en suivant les instructions ci-dessus. +2. Activez **Stocker les jetons pour un accès API persistant** dans le connecteur Logto OIDC d’entreprise. Logto stockera en toute sécurité les jetons d’accès dans le Secret Vault. +3. Pour les fournisseurs d’identité OIDC **standards**, la portée `offline_access` doit être incluse pour obtenir un jeton de rafraîchissement (Refresh token), évitant ainsi de demander à plusieurs reprises le consentement de l’utilisateur. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..01d666a440a --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +Fournissez les `domaines e-mail` de votre organisation dans l’onglet `Expérience SSO` du connecteur Logto. Cela activera le connecteur SSO comme méthode d’authentification pour ces utilisateurs. + +Les utilisateurs ayant des adresses e-mail dans les domaines spécifiés seront redirigés pour utiliser votre connecteur SSO comme seule méthode d’authentification. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index b4c5857bb40..e8173462a23 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -4,43 +4,47 @@ sidebar_position: 2 # Déploiement et configuration -Dans l'article précédent, nous avons couvert les bases pour [démarrer rapidement avec Logto](/logto-oss/get-started-with-oss). Cet article approfondit le sujet, en se concentrant sur les meilleures pratiques et les étapes de configuration détaillées pour déployer Logto dans un environnement de production. +Dans l'article précédent, nous avons abordé les bases pour [démarrer rapidement avec Logto](/logto-oss/get-started-with-oss). Cet article va plus loin, en se concentrant sur les bonnes pratiques et les étapes de configuration détaillées pour déployer Logto dans un environnement de production. ## Variables d'environnement \{#environment-variables} -Nous utilisons un ensemble généré de variables d'environnement dans notre démo (`docker-compose.yml`), que vous devriez remplacer par les vôtres et maintenir la cohérence entre plusieurs instances de Logto. +Nous utilisons un ensemble généré de variables d'environnement dans notre démo (`docker-compose.yml`), que vous devez remplacer par les vôtres et maintenir la cohérence entre plusieurs instances Logto. Vous pouvez définir les variables d'environnement directement ou placer un fichier `.env` à la racine du projet Logto. Si vous testez avec Docker, consultez le fichier `.env` généré de l'image dans `/etc/logto`. ### Essentiels \{#essentials} - `DB_URL` Le [DSN Postgres](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) pour la base de données Logto. -- `PORT` Le port auquel Logto écoute. Par défaut `3001`. -- `ENDPOINT` Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (par exemple, `ENDPOINT=https://logto.domain.com`). Cela affectera également la valeur de l'[identifiant de l'émetteur OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). +- `PORT` Le port sur lequel Logto écoute. Par défaut `3001`. +- `ENDPOINT` Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (ex. `ENDPOINT=https://logto.domain.com`). Cela affectera également la valeur de l'[identifiant d'émetteur OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). **Activer la console d'administration** -- `ADMIN_PORT` Le port auquel la console d'administration Logto écoute. Par défaut `3002`. -- `ADMIN_ENDPOINT` Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (par exemple, `ADMIN_ENDPOINT=https://admin.domain.com`). Cela affectera également la valeur des URIs de redirection de la console d'administration. +- `ADMIN_PORT` Le port sur lequel la console d'administration Logto écoute. Par défaut `3002`. +- `ADMIN_ENDPOINT` Vous pouvez spécifier une URL avec votre domaine personnalisé pour la production (ex. `ADMIN_ENDPOINT=https://admin.domain.com`). Cela affectera également la valeur des URI de redirection de la console d'administration. **Désactiver la console d'administration** -- `ADMIN_DISABLE_LOCALHOST` Réglez-le sur `1` ou `true` pour fermer le port de la console d'administration. Si `ADMIN_ENDPOINT` n'est pas défini, cela désactivera complètement la console d'administration. +- `ADMIN_DISABLE_LOCALHOST` Mettez la valeur à `1` ou `true` pour fermer le port de la console d'administration. Si `ADMIN_ENDPOINT` n'est pas défini, cela désactivera complètement la console d'administration. Pour plus de détails sur les variables d'environnement, voir [Configuration](/concepts/core-service/configuration/). +**Activer Secret Vault** + +- Pour utiliser le [Secret Vault](/secret-vault), vous devez définir `SECRET_VAULT_KEK` avec une chaîne encodée en base64 de votre clé de chiffrement principale (KEK). Celle-ci est utilisée pour chiffrer les clés de chiffrement des données (DEK) dans le Secret Vault. AES-256 (32 octets) est recommandé. Exemple : `crypto.randomBytes(32).toString('base64')`. + ### HTTPS \{#https} -Vous pouvez utiliser Node.js pour servir HTTPS directement ou configurer un proxy / équilibreur HTTPS devant Node.js. Voir [Activer HTTPS](/concepts/core-service/configuration/#enabling-https) pour plus de détails. +Vous pouvez utiliser Node.js pour servir directement en HTTPS ou configurer un proxy / équilibreur HTTPS devant Node.js. Voir [Activation du HTTPS](/concepts/core-service/configuration/#enabling-https) pour plus de détails. ### Proxy inverse \{#reverse-proxy} -Si vous souhaitez utiliser un proxy inverse sur votre serveur, par exemple Nginx ou Apache, vous devez mapper les ports 3001 et 3002 séparément dans vos paramètres de proxy pass. En supposant que vous utilisez Nginx, votre point de terminaison d'authentification Logto fonctionne sur le port 3001, et votre console d'administration Logto fonctionne sur le port 3002, mettez la configuration suivante dans nginx.conf : +Si vous souhaitez utiliser un proxy inverse sur votre serveur, par exemple Nginx ou Apache, vous devez mapper séparément les ports 3001 et 3002 dans vos paramètres de proxy pass. En supposant que vous utilisez Nginx, que votre endpoint d'auth Logto fonctionne sur le port 3001, et que votre console d'administration Logto fonctionne sur le port 3002, placez la configuration suivante dans nginx.conf : ``` server { listen 443 ssl; - server_name ; // par exemple, auth.your-domain.com + server_name ; // ex. auth.votre-domaine.com ... location / { @@ -52,8 +56,8 @@ server { proxy_pass http://127.0.0.1:3001; } - ssl_certificate ; - ssl_certificate_key + ssl_certificate ; + ssl_certificate_key ... } ``` @@ -63,7 +67,7 @@ Ajoutez ensuite une configuration similaire pour votre console d'administration ``` server { listen 443 ssl; - server_name ; // par exemple, admin.your-domain.com + server_name ; // ex. admin.votre-domaine.com ... location / { @@ -75,27 +79,27 @@ server { proxy_pass http://127.0.0.1:3002; } - ssl_certificate ; - ssl_certificate_key + ssl_certificate ; + ssl_certificate_key ... } ``` -Rechargez la configuration Nginx pour prendre en compte les dernières modifications : +Rechargez la configuration Nginx pour prendre en compte les derniers changements : ``` nginx -s reload ``` -Tout est prêt. Ouvrez le navigateur et visitez `https://admin.your-domain.com`, vous devriez voir la page d'accueil de Logto. +Tout est prêt. Ouvrez le navigateur et visitez `https://admin.votre-domaine.com`, vous devriez voir la page d'accueil Logto. ## Conteneurisation \{#containerization} -Pour la production, vous pouvez utiliser Docker pour conteneuriser Logto. Vous pouvez trouver le Dockerfile dans le répertoire racine du projet. Si vous souhaitez exécuter plusieurs instances de Logto, par exemple, déployer Logto dans un cluster Kubernetes, il y a quelques étapes supplémentaires à suivre. +Pour la production, vous pouvez utiliser Docker pour conteneuriser Logto. Vous trouverez le Dockerfile à la racine du projet. Si vous souhaitez exécuter plusieurs instances de Logto, par exemple déployer Logto dans un cluster Kubernetes, il y a quelques étapes supplémentaires à suivre. -### Dossier de connecteurs partagé \{#shared-connectors-folder} +### Dossier des connecteurs partagé \{#shared-connectors-folder} -Par défaut, Logto créera un dossier `connectors` dans le répertoire racine du dossier `core`. Nous recommandons de partager le dossier entre plusieurs instances de Logto, vous devez monter le dossier `packages/core/connectors` dans le conteneur et exécuter `npm run cli connector add -- --official` pour déployer les connecteurs. +Par défaut, Logto créera un dossier `connectors` dans le répertoire racine du dossier `core`. Nous recommandons de partager ce dossier entre plusieurs instances de Logto ; vous devez monter le dossier `packages/core/connectors` dans le conteneur et exécuter `npm run cli connector add -- --official` pour déployer les connecteurs. Voici un exemple minimal de `deployment` pour Kubernetes : @@ -130,7 +134,7 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -Dans cet exemple, nous créons un répertoire vide en tant que volume et le montons dans les conteneurs. Ensuite, nous exécutons `npm run cli connector add -- --official` dans le conteneur d'initialisation pour télécharger les connecteurs. Enfin, chaque conteneur partagera le même dossier de connecteurs avec nos connecteurs officiels déjà à l'intérieur. +Dans cet exemple, nous créons un dossier vide comme volume et le montons dans les conteneurs. Ensuite, nous exécutons `npm run cli connector add -- --official` dans le conteneur d'initialisation pour télécharger les connecteurs. Enfin, chaque conteneur partagera le même dossier de connecteurs avec nos connecteurs officiels déjà présents. :::note @@ -138,11 +142,11 @@ Ceci est un exemple de yaml, pour exécuter Logto, vous devez définir correctem ::: -Pour la production, vous pouvez remplacer le volume "empty dir" par un volume persistant, et faire le travail "init" à votre manière, vous savez ce que vous faites ! +Pour la production, vous pouvez remplacer le volume "empty dir" par un volume persistant, et effectuer le travail "init" à votre façon, vous savez ce que vous faites ! ### Modification de la base de données \{#database-alteration} -Similaire aux connecteurs, la modification de la base de données doit être exécutée dans une seule instance. Vous pouvez utiliser un job pour exécuter le script de modification. +Comme pour les connecteurs, la modification de la base de données doit être exécutée sur une seule instance. Vous pouvez utiliser un job pour exécuter le script de modification. La variable d'environnement `CI=true` est nécessaire lorsque la modification est exécutée de manière non interactive. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..af8c34b81a3 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# Coffre-fort de secrets + +Le Coffre-fort de secrets dans Logto est conçu pour stocker en toute sécurité les données sensibles des utilisateurs — telles que les jetons d’accès (Access tokens), les clés API, les codes d’accès ou toute autre information confidentielle nécessitant une protection. Ces secrets sont souvent utilisés pour accéder à des services tiers au nom de l’utilisateur, rendant le stockage sécurisé essentiel. + +## Schéma de chiffrement \{#encryption-scheme} + +Pour protéger les données sensibles, le Coffre-fort de secrets utilise un schéma de chiffrement robuste basé sur les **clés de chiffrement des données (DEK)** et les **clés de chiffrement de clés (KEK)**. + +- **Chiffrement par secret :** Chaque secret est chiffré avec sa propre DEK unique, garantissant que même si une clé est compromise, les autres secrets restent protégés. +- **Enrobage de clé :** La DEK elle-même est chiffrée (ou "enrobée") avec une KEK, qui est gérée et stockée de manière sécurisée par le système. +- **Sécurité en couches :** Cette approche à deux niveaux garantit que même si une partie du système est compromise, les attaquants ne peuvent pas accéder aux secrets sans la DEK et la KEK. +- **Exposition minimisée :** Les secrets ne sont déchiffrés que lorsque cela est absolument nécessaire, réduisant ainsi le risque d’exposition accidentelle et respectant les meilleures pratiques pour la gestion des données sensibles. + +Ce modèle de chiffrement en couches offre une protection solide pour les identifiants et jetons les plus sensibles des utilisateurs, tout en permettant un accès sécurisé lorsque cela est nécessaire. + +## Types de secrets \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +Actuellement, l’ensemble de jetons fédérés est le seul type de secret pris en charge nativement. Cependant, le Coffre-fort de secrets est conçu pour accueillir tout type d’information sensible. Si vous avez besoin de la prise en charge d’autres types de secrets, veuillez [nous contacter](https://logto.io/contact) — nous serons ravis de vous aider. +::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..20bef12eee3 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: Ensemble de jetons fédérés +sidebar_label: Ensemble de jetons fédérés +--- + +import Availability from '@components/Availability'; + + + +L'ensemble de jetons fédérés est un type de secret stocké dans le Secret Vault de Logto, utilisé pour gérer en toute sécurité les jetons d’accès (Access tokens) et de rafraîchissement (Refresh tokens) émis par des fournisseurs d'identité tiers fédérés. Lorsqu'un utilisateur s'authentifie via un connecteur social ou SSO d’entreprise, Logto stocke les jetons émis dans le coffre. Ces jetons peuvent ensuite être récupérés pour accéder aux API tierces au nom de l'utilisateur, sans nécessiter de nouvelle authentification. + +## Activer le stockage des jetons fédérés \{#enable-federated-token-storage} + +### Connecteurs sociaux \{#social-connectors} + +:::Info +Cette fonctionnalité est uniquement disponible pour les connecteurs prenant en charge le stockage des jetons. Les connecteurs actuellement pris en charge incluent : [GitHub](/integrations/github), [Google](/integrations/google), [Facebook](/integrations/facebook), [OAuth 2.0 standard](/integrations/oauth2) et [OIDC standard](/integrations/oidc). La prise en charge d'autres connecteurs sera déployée progressivement. +::: + +1. Accédez à Console > Connecteurs > Connecteurs sociaux. +2. Sélectionnez le connecteur social pour lequel vous souhaitez activer le stockage des jetons fédérés. +3. Dans la page "Paramètres", activez l’option **Stocker les jetons pour un accès API persistant**. + +### Connecteurs SSO d’entreprise \{#enterprise-sso-connectors} + +:::Info +Le stockage des jetons est disponible pour tous les connecteurs d’entreprise OIDC. +::: + +1. Accédez à Console > SSO d’entreprise. +2. Sélectionnez le connecteur SSO d’entreprise pour lequel vous souhaitez activer le stockage des jetons fédérés. +3. Dans l’onglet "Expérience SSO", activez l’option **Stocker les jetons pour un accès API persistant**. + +Assurez-vous d’enregistrer vos modifications. + +## Stockage des jetons \{#token-storage} + +Une fois le stockage des jetons fédérés activé, Logto stocke automatiquement les jetons d’accès (Access tokens) et de rafraîchissement (Refresh tokens) émis par le fournisseur d’identité fédéré chaque fois qu’un utilisateur s’authentifie via un connecteur social ou SSO d’entreprise. Cela inclut : + +- [Connexion et inscription sociale](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [Connexion et inscription SSO d’entreprise](/end-user-flows/enterprise-sso) +- [Liaison de compte social via l’Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +Les jetons stockés sont attachés à l'identité sociale ou SSO d’entreprise de l'utilisateur, ce qui leur permet de récupérer les jetons ultérieurement pour accéder à l’API sans nécessiter de nouvelle authentification. + +### Vérification du statut de stockage des jetons \{#checking-token-storage-status} + +Vous pouvez vérifier le statut de stockage des jetons fédérés d’un utilisateur dans la Console Logto : + +1. Accédez à Console > Utilisateurs. +2. Cliquez sur l’utilisateur que vous souhaitez inspecter. Cela vous amènera à la page de détails de l’utilisateur. +3. Faites défiler jusqu’à la section **Connexions**. Cette zone répertorie toutes les connexions sociales et SSO d’entreprise associées à l’utilisateur. +4. Chaque entrée de connexion affiche une étiquette de statut de jeton indiquant si des jetons sont stockés pour cette connexion. +5. Cliquez sur l’entrée de connexion pour afficher plus de détails, y compris les métadonnées du jeton d’accès stocké et la disponibilité du jeton de rafraîchissement (le cas échéant). + +Vous pouvez également vérifier les identités tierces de l’utilisateur et le statut de stockage des jetons via la Management API : + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true` : Récupérer l'identité sociale d’un utilisateur et le statut de stockage des jetons associé à l'identité par un connecteur cible donné (par exemple, `github`, `google`, etc.). +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true` : Récupérer l'identité SSO d’entreprise d’un utilisateur et le statut de stockage des jetons associé à l'identité par un ID de connecteur SSO donné. + +### Statut de stockage des jetons \{#token-storage-status} + +- **Actif** : Le jeton d’accès est stocké et actif. +- **Expiré** : Le jeton d’accès est stocké mais a expiré. Si un jeton de rafraîchissement est disponible, il peut être utilisé pour obtenir un nouveau jeton d’accès. +- **Inactif** : Aucun jeton d’accès n’est stocké pour cette connexion. Cela peut se produire si l’utilisateur ne s’est pas authentifié via cette connexion ou si le stockage du jeton a été supprimé. +- **Non applicable** : Le connecteur ne prend pas en charge le stockage des jetons. + +### Métadonnées du jeton \{#token-metadata} + +Pour l’intégrité des données et la sécurité, tous les jetons sont chiffrés avant d’être stockés dans le Secret Vault. Les valeurs réelles des jetons ne sont accessibles qu’à l’utilisateur final avec la bonne autorisation. Les développeurs, quant à eux, ne peuvent récupérer que les métadonnées de l’ensemble de jetons pour comprendre l’état des jetons stockés sans exposer de contenu sensible. + +- `createdAt` : L’horodatage de la première création de la connexion et du stockage initial de l’ensemble de jetons dans le Secret Vault. +- `updatedAt` : La dernière fois que l’ensemble de jetons a été mis à jour. + - Si aucun jeton de rafraîchissement n’est disponible, cette valeur sera identique à **createdAt**. + - Si un jeton de rafraîchissement est présent, cette valeur reflète la dernière fois que le jeton d’accès a été rafraîchi. +- `hasRefreshToken` : Indique si un jeton de rafraîchissement est disponible. + Si le connecteur prend en charge l’accès hors ligne et que la requête d’autorisation est correctement configurée, Logto stocke le jeton de rafraîchissement lorsqu’il est émis par le fournisseur d’identité en même temps que le jeton d’accès. + Lorsque le jeton d’accès expire et qu’un jeton de rafraîchissement valide existe, Logto tente automatiquement d’obtenir un nouveau jeton d’accès à l’aide du jeton de rafraîchissement stocké chaque fois que l’utilisateur demande l’accès au fournisseur connecté. +- `expiresAt` : L’heure d’expiration estimée du jeton d’accès en **secondes**. + Ceci est calculé à partir de la valeur `expires_in` renvoyée par le point de terminaison de jeton du fournisseur d’identité. (Ce champ n’est disponible que si le fournisseur inclut `expires_in` dans la réponse du jeton.) +- `scope` : La portée (Scope) du jeton d’accès, indiquant les permissions accordées par le fournisseur d’identité. + Ceci est utile pour comprendre quelles actions peuvent être effectuées avec le jeton d’accès stocké. (Ce champ n’est disponible que si le fournisseur inclut `scope` dans la réponse du jeton.) +- `tokenType` : Le type du jeton d’accès, généralement "Bearer". + (Ce champ n’est disponible que si le fournisseur inclut `token_type` dans la réponse du jeton.) + +## Récupération des jetons \{#token-retrieval} + +Une fois le stockage des jetons activé et les jetons stockés en toute sécurité dans le Secret Vault de Logto, les utilisateurs finaux peuvent récupérer leurs jetons d’accès tiers depuis votre application cliente en intégrant l’[Account API](/end-user-flows/account-settings/by-account-api) de Logto. + +- `GET /my-account/identities/:target/access-token` : Récupérer le jeton d’accès pour une identité sociale en spécifiant le connecteur cible (par exemple, github, google). + +- `GET /my-account/sso-identities/:connectorId/access-token` : Récupérer le jeton d’accès pour une identité SSO d’entreprise en spécifiant l’ID du connecteur. + +:::info +Découvrez comment [activer](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) et [accéder](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) à l’Account API en utilisant le jeton d’accès émis par Logto. +::: + +### Rotation des jetons \{#token-rotation} + +Les points de terminaison de récupération des jetons renvoient : + +- `200` OK : Si le jeton d’accès est récupéré avec succès et est toujours valide. +- `404` Not Found : Si l’utilisateur ne possède pas d’identité sociale ou SSO d’entreprise associée à la cible ou à l’ID du connecteur spécifié, ou si le jeton d’accès n’est pas stocké. +- `401` Unauthorized : Si le jeton d’accès est expiré. + +Si le jeton d’accès est expiré et qu’un jeton de rafraîchissement est disponible, Logto tente automatiquement de rafraîchir le jeton d’accès et renvoie le nouveau jeton d’accès dans la réponse. Le stockage du jeton dans le Secret Vault est également mis à jour avec le nouveau jeton d’accès et ses métadonnées. + +## Suppression du stockage des jetons \{#token-storage-deletion} + +Le stockage des jetons fédérés est directement lié à chaque connexion sociale ou SSO d’entreprise de l’utilisateur. Cela signifie que l’ensemble de jetons stocké sera automatiquement supprimé dans les cas suivants : + +- L’identité sociale ou SSO d’entreprise associée est supprimée du compte de l’utilisateur. +- Le compte utilisateur est supprimé de votre tenant. +- Le connecteur social ou SSO d’entreprise est supprimé de votre tenant. + +### Révocation des jetons \{#revoking-tokens} + +Vous pouvez également supprimer manuellement l’ensemble de jetons tiers d’un utilisateur pour révoquer l’accès : + +- Depuis la Console : + Accédez à la page de détails de l’identité de l’utilisateur. Faites défiler jusqu’à la section **Jeton d’accès** (si le stockage des jetons est disponible) et cliquez sur le bouton **Supprimer les jetons** à la fin de la section. +- Via la Management API : + - `DELETE /api/secret/:id` : Supprimer un secret spécifique par son ID, qui peut être obtenu à partir des détails de l’identité de l’utilisateur. + +La révocation de l’ensemble de jetons obligera l’utilisateur à se réauthentifier auprès du fournisseur tiers pour obtenir un nouveau jeton d’accès avant de pouvoir accéder à nouveau aux API tierces. + +## Réauthentification et renouvellement des jetons \{#reauthentication-and-token-renewal} + +Dans les scénarios où un jeton d’accès stocké a expiré ou lorsqu’une application doit demander des portées (Scopes) API supplémentaires, les utilisateurs finaux peuvent se réauthentifier auprès du fournisseur tiers pour obtenir un nouveau jeton d’accès — sans avoir besoin de se reconnecter à Logto. +Cela peut être réalisé via l’[API de vérification sociale](https://openapi.logto.io/operation/operation-createverificationbysocial) de Logto, qui permet aux utilisateurs de relancer un flux d’autorisation sociale fédérée et de mettre à jour leur ensemble de jetons stocké. + +:::note +La relance de l’autorisation fédérée est actuellement limitée aux connecteurs sociaux. +Pour les connecteurs SSO d’entreprise, la réauthentification et le renouvellement des jetons nécessitent que l’utilisateur initie à nouveau un flux d’authentification Logto complet, car la réautorisation directe auprès du fournisseur SSO d’entreprise n’est actuellement pas prise en charge après la connexion. +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as Utilisateur + participant Logto as Logto + participant Provider as Fournisseur tiers + + User->>Logto: post /api/verification/social + Logto->>User: Rediriger vers le fournisseur tiers + User->>Provider: S’authentifier et autoriser + Provider->>User: Rediriger avec le code d’autorisation + User->>Logto: post /api/verification/social/verify avec le code d’autorisation + Logto->>User: Retourner l’ID de vérification sociale + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. L’utilisateur initie une demande de vérification sociale en appelant le point de terminaison `POST /api/verification/social`. L’utilisateur peut spécifier des portées personnalisées pour demander des permissions supplémentaires au fournisseur tiers. + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header** : Le jeton d’accès de l’utilisateur émis par Logto. + - **connectorId** : L’ID du connecteur social dans Logto. + - **redirectUri** : L’URI vers lequel rediriger l’utilisateur après l’authentification. Vous devrez enregistrer cet URI dans les paramètres de l’application du fournisseur. + - **scope** : (Optionnel) Portées personnalisées pour demander des permissions supplémentaires au fournisseur tiers. Si non spécifié, les portées par défaut configurées dans le connecteur seront utilisées. + +2. Logto crée un nouvel enregistrement de vérification sociale et retourne l’ID de vérification sociale ainsi que l’URL d’autorisation pour rediriger l’utilisateur vers le fournisseur tiers pour l’authentification. + + La réponse ressemblera à ceci : + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. Redirigez l’utilisateur vers l’URL d’autorisation. L’utilisateur s’authentifie auprès du fournisseur tiers et accorde les permissions. + +4. Le fournisseur tiers redirige l’utilisateur vers votre application cliente avec un code d’autorisation. + +5. Gérez le rappel d’autorisation en transmettant le code d’autorisation au point de terminaison de vérification de Logto : + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header** : Le jeton d’accès de l’utilisateur émis par Logto. + - **verificationRecordId** : L’ID de vérification sociale retourné à l’étape précédente. + - **connectorData** : Le code d’autorisation et toute autre donnée renvoyée par le fournisseur tiers lors du rappel. + + :::note + N’oubliez pas de valider le paramètre `state` pour prévenir les attaques CSRF. + ::: + +6. Logto vérifie le code d’autorisation et l’échange contre un nouveau jeton d’accès et un jeton de rafraîchissement auprès du fournisseur tiers, puis retourne l’ID de vérification sociale dans la réponse. + +7. Enfin, mettez à jour le stockage des jetons de l’utilisateur en appelant le point de terminaison `PATCH /my-account/identities/:target/access-token` avec l’ID de vérification sociale : + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header** : Le jeton d’accès de l’utilisateur émis par Logto. + - **socialVerificationId** : L’ID d’enregistrement de vérification sociale vérifié retourné à l’étape précédente. + + Cela mettra à jour l’ensemble de jetons de l’utilisateur dans le Secret Vault de Logto avec le nouveau jeton d’accès et le jeton de rafraîchissement, permettant à l’utilisateur d’accéder aux API tierces sans avoir besoin de se reconnecter à Logto. + + Le jeton d’accès mis à jour sera retourné. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 83a1c5bdba9..45fb19273c7 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -20,26 +20,38 @@ Après avoir configuré le [Management API](/integrate-logto/interact-with-manag Après avoir créé un PAT, vous pouvez l’utiliser pour accorder des jetons d’accès à votre application en utilisant le point de terminaison d’échange de jetons. +:::tip Équivalence des flux de jetons + +Les jetons d’accès obtenus à l’aide des PATs fonctionnent **de manière identique** aux jetons obtenus via le flux standard `refresh_token`. Cela signifie : + +- **Contexte d’organisation** : Les jetons obtenus via PAT prennent en charge les mêmes permissions d’organisation et portées (scopes) que les flux de jeton de rafraîchissement +- **Flux d’autorisation** : Vous pouvez utiliser les jetons d’accès échangés via PAT pour les [permissions d’organisation](/authorization/organization-permissions) et les [ressources API au niveau de l’organisation](/authorization/organization-level-api-resources) +- **Validation du jeton** : La même logique de validation s’applique – seul le type de grant initial diffère + +Si vous travaillez avec des organisations, les modèles d’accès et les permissions sont les mêmes que vous utilisiez un PAT ou un jeton de rafraîchissement. + +::: + ### Requête \{#request} L’application effectue une [requête d’échange de jeton](https://auth.wiki/authorization-code-flow#token-exchange-request) vers le [point de terminaison de jeton](/integrate-logto/application-data-structure#token-endpoint) du tenant avec un type de grant spécial en utilisant la méthode HTTP POST. Les paramètres suivants sont inclus dans le corps de la requête HTTP au format `application/x-www-form-urlencoded`. -1. `client_id` : OBLIGATOIRE. L’ID client de l’application. +1. `client_id` : OBLIGATOIRE. L’identifiant client de l’application. 2. `grant_type` : OBLIGATOIRE. La valeur de ce paramètre doit être `urn:ietf:params:oauth:grant-type:token-exchange` pour indiquer qu’un échange de jeton est en cours. -3. `resource` : OPTIONNEL. L’indicateur de ressource (Resource indicator), comme pour les autres requêtes de jeton. -4. `scope` : OPTIONNEL. Les portées (Scopes) demandées, comme pour les autres requêtes de jeton. +3. `resource` : OPTIONNEL. L’indicateur de ressource, identique aux autres requêtes de jeton. +4. `scope` : OPTIONNEL. Les portées demandées, identiques aux autres requêtes de jeton. 5. `subject_token` : OBLIGATOIRE. Le PAT de l’utilisateur. 6. `subject_token_type` : OBLIGATOIRE. Le type de jeton de sécurité fourni dans le paramètre `subject_token`. La valeur de ce paramètre doit être `urn:logto:token-type:personal_access_token`. ### Réponse \{#response} -Si la requête d’échange de jeton réussit, le point de terminaison de jeton du tenant retourne un jeton d’accès représentant l’identité de l’utilisateur. La réponse inclut les paramètres suivants dans le corps de la réponse HTTP au format `application/json`. +Si la requête d’échange de jeton réussit, le point de terminaison de jeton du tenant retourne un jeton d’accès qui représente l’identité de l’utilisateur. La réponse inclut les paramètres suivants dans le corps de la réponse HTTP au format `application/json`. -1. `access_token` : OBLIGATOIRE. Le jeton d’accès (Access token) de l’utilisateur, identique aux autres requêtes de jeton comme `authorization_code` ou `refresh_token`. +1. `access_token` : OBLIGATOIRE. Le jeton d’accès de l’utilisateur, identique aux autres requêtes de jeton comme `authorization_code` ou `refresh_token`. 2. `issued_token_type` : OBLIGATOIRE. Le type du jeton émis. La valeur de ce paramètre doit être `urn:ietf:params:oauth:token-type:access_token`. 3. `token_type` : OBLIGATOIRE. Le type du jeton. La valeur de ce paramètre doit être `Bearer`. 4. `expires_in` : OBLIGATOIRE. La durée de vie en secondes du jeton d’accès. -5. `scope` : OPTIONNEL. Les portées (Scopes) du jeton d’accès. +5. `scope` : OPTIONNEL. Les portées du jeton d’accès. ### Exemple d’échange de jeton \{#example-token-exchange} @@ -85,11 +97,10 @@ Exemple de payload du jeton d’accès : ## Ressources associées \{#related-resources} - Qu’est-ce qu’un jeton d’accès personnel (Personal access token) ? Quand dois-je utiliser les - jetons d’accès personnels ? + Qu’est-ce qu’un jeton d’accès personnel ? Quand dois-je utiliser les jetons d’accès personnels ? - Jetons d’accès personnels (Personal Access Tokens), authentification machine à machine - (Machine-to-Machine authentication), définitions des clés API (API Keys) et leurs scénarios réels + Jetons d’accès personnels, authentification machine à machine (Machine-to-Machine), et définition + des clés API ainsi que leurs scénarios d’utilisation réels diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index f1fe37f465d..465a6d08b7e 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -11,16 +11,18 @@ Logto prend en charge la migration manuelle des utilisateurs existants depuis un Avant de commencer, examinons le [schéma utilisateur](/user-management/user-data/#user-profile) dans Logto. Il y a 3 parties du schéma utilisateur dont vous devez être conscient : 1. **Données de base** : il s'agit des informations de base du profil utilisateur, vous pouvez faire correspondre les données de votre profil utilisateur existant. -2. **Données personnalisées** : stocke des informations utilisateur supplémentaires, vous pouvez l'utiliser pour stocker des fichiers qui ne correspondent pas aux données de base. +2. **Données personnalisées** : stocke des informations utilisateur supplémentaires, vous pouvez utiliser cette section pour stocker des fichiers qui ne correspondent pas aux données de base. 3. **Identités sociales** : stocke les informations utilisateur récupérées lors de la connexion sociale. -Vous pouvez créer une correspondance pour faire le lien entre les informations de votre profil utilisateur existant et les **données de base** et **données personnalisées**. Pour la connexion sociale, des étapes supplémentaires sont nécessaires pour importer les identités sociales ; veuillez vous référer à l’API de [Lier une identité sociale à un utilisateur](https://openapi.logto.io/operation/operation-createuseridentity). +Vous pouvez créer une correspondance pour faire le lien entre les informations de votre profil utilisateur existant et les **données de base** et **données personnalisées**. Pour la connexion sociale, des étapes supplémentaires sont nécessaires pour importer les identités sociales ; veuillez consulter l’API [Lier une identité sociale à un utilisateur](https://openapi.logto.io/operation/operation-createuseridentity). ## Hachage des mots de passe \{#password-hashing} -Logto utilise [Argon2](https://en.wikipedia.org/wiki/Argon2) pour hacher le mot de passe de l'utilisateur, et prend également en charge d'autres algorithmes comme `MD5`, `SHA1`, `SHA256` et `Bcrypt` pour faciliter la migration. Ces algorithmes sont considérés comme non sécurisés, les mots de passe correspondants seront migrés vers Argon2 lors de la première connexion réussie de l'utilisateur. +Logto utilise [Argon2](https://en.wikipedia.org/wiki/Argon2) pour hacher le mot de passe de l'utilisateur, et prend également en charge d'autres algorithmes comme `MD5`, `SHA1`, `SHA256` et `Bcrypt` pour faciliter la migration. Ces algorithmes sont considérés comme non sécurisés, les hachages de mots de passe correspondants seront migrés vers Argon2 lors de la première connexion réussie de l'utilisateur. -Si vous utilisez d'autres algorithmes de hachage ou du sel, vous pouvez définir `passwordAlgorithm` sur `Legacy`, ce qui vous permet d'utiliser n'importe quel algorithme de hachage pris en charge par Node.js. Vous pouvez trouver la liste des algorithmes pris en charge dans la [documentation Node.js crypto](https://nodejs.org/api/crypto.html#cryptogethashes). Dans ce cas, le `passwordDigest` sera une chaîne JSON contenant l'algorithme de hachage et d'autres paramètres spécifiques à l'algorithme. +Si vous utilisez d'autres algorithmes de hachage ou du sel, vous pouvez définir `passwordAlgorithm` sur `Legacy`, ce qui vous permet d'utiliser n'importe quel algorithme de hachage pris en charge par Node.js. Vous trouverez la liste des algorithmes pris en charge dans la [documentation crypto de Node.js](https://nodejs.org/api/crypto.html#cryptogethashes). Dans ce cas, le `passwordDigest` sera une chaîne JSON contenant l'algorithme de hachage et d'autres paramètres spécifiques à l'algorithme. + +### Format général Legacy \{#general-legacy-format} Le format de la chaîne JSON est le suivant : @@ -44,6 +46,36 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### Prise en charge de PBKDF2 \{#pbkdf2-support} + +Logto prend spécifiquement en charge [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2). + +Pour migrer des mots de passe hachés avec PBKDF2, définissez `passwordAlgorithm` sur `Legacy` et formatez le `passwordDigest` comme suit : + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +Les paramètres sont : + +- **`salt`** : La valeur du sel utilisée dans le hachage d'origine +- **`iterations`** : Nombre d'itérations (ex : `"1000"`) +- **`keylen`** : Longueur de la clé dérivée en octets (ex : `"20"`) +- **`digest`** : La fonction de hachage utilisée (ex : `"sha512"`, `"sha256"`, `"sha1"`) +- **`@`** : Espace réservé pour la valeur réelle du mot de passe +- **`expected_hashed_value`** : Le résultat attendu du hachage sous forme de chaîne hexadécimale + +**Exemple de charge utile de migration :** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## Étapes de migration \{#steps-to-migrate} 1. **Préparer les données utilisateur** @@ -65,11 +97,11 @@ const expectedHashedValue = hash.digest('hex'); ``` 2. **Créer un tenant Logto** - Vous devrez configurer un tenant dans Logto. Vous pouvez utiliser Logto Cloud ou Logto OSS. Si ce n'est pas déjà fait, veuillez consulter le guide [Configurer Logto cloud](/introduction/set-up-logto-cloud/#create-logto-tenant). + Vous devrez configurer un tenant dans Logto. Vous pouvez utiliser Logto Cloud ou Logto OSS. Si ce n'est pas encore fait, veuillez consulter le guide [Configurer Logto cloud](/introduction/set-up-logto-cloud/#create-logto-tenant). 3. **Configurer la connexion à Management API** Nous utiliserons Management API pour importer les données utilisateur. Vous pouvez consulter la page [Management API](/integrate-logto/interact-with-management-api) pour apprendre à configurer la connexion dans votre environnement de développement. 4. **Importer les données utilisateur** - Il est recommandé de préparer un script pour importer les données utilisateur une par une. Nous appellerons l’API [create user](https://openapi.logto.io/operation/operation-createuser) pour importer les données utilisateur. Voici un exemple de script : + Il est recommandé de préparer un script pour importer les données utilisateur une par une. Nous appellerons l’API [créer un utilisateur](https://openapi.logto.io/operation/operation-createuser) pour importer les données utilisateur. Voici un exemple de script : ```jsx const users = require('./users.json'); @@ -85,10 +117,12 @@ const expectedHashedValue = hash.digest('hex'); }, body: JSON.stringify(user), }); - // Sleep for a while to avoid rate limit + // Pause pour éviter la limite de débit await new Promise((resolve) => setTimeout(resolve, 200)); } catch (error) { - console.error(`Failed to import user ${user.username}: ${error.message}`); + console.error( + `Échec de l'importation de l'utilisateur ${user.username} : ${error.message}` + ); } } }; @@ -96,7 +130,7 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -Veuillez noter que le point d’API est soumis à une limitation de débit ; vous devez ajouter une pause entre chaque requête pour éviter d’atteindre la limite. Veuillez consulter notre page sur les [limitations de débit](/integrate-logto/interact-with-management-api/#rate-limit) pour plus de détails. +Veuillez noter que le point d'accès API est soumis à une limite de débit ; vous devez ajouter une pause entre chaque requête pour éviter la limite. Veuillez consulter notre page [limites de débit](/integrate-logto/interact-with-management-api/#rate-limit) pour plus de détails. Si vous avez un grand volume de données utilisateur (plus de 100 000 utilisateurs), vous pouvez [nous contacter](https://logto.io/contact) pour augmenter la limite de débit. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/ja/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index ec72118cb55..a4a583db769 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -2,12 +2,12 @@ ## 環境変数 {#environment-variables} -### 使用法 {#usage} +### 使い方 {#usage} Logto は環境変数を次の順序で処理します： - システム環境変数 -- プロジェクトルートの `.env` ファイル（[dotenv](https://github.com/motdotla/dotenv#readme) 形式に準拠） +- プロジェクトルートの `.env` ファイル（ [dotenv](https://github.com/motdotla/dotenv#readme) 形式に準拠） したがって、システム環境変数は `.env` の値を上書きします。 @@ -17,51 +17,52 @@ Logto は環境変数を次の順序で処理します： プロジェクトルートで `npm start` を使用して Logto を実行する場合、`NODE_ENV` は常に `production` になります。 ::: -デフォルト値では、`protocol` は HTTPS 設定に応じて `http` または `https` になります。 - -| Key | Default Value | Type | Description | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto が実行される環境の種類。 | -| PORT | `3001` | `number` | Logto がリッスンするローカルポート。 | -| ADMIN_PORT | `3002` | `number` | Logto 管理コンソールがリッスンするローカルポート。 | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 管理コンソールのポートを無効にするには `1` または `true` に設定します。`ADMIN_ENDPOINT` が設定されていない場合、管理コンソールは完全に無効になります。 | -| DB_URL | N/A | `string` | Logto データベースのための [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 | -| HTTPS_CERT_PATH | `undefined` | string | undefined | 詳細は [HTTPS の有効化](#enabling-https) を参照してください。 | -| HTTPS_KEY_PATH | `undefined` | string | undefined | 同上。 | -| TRUST_PROXY_HEADER | `false` | `boolean` | 同上。 | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | オンラインテストや本番用にカスタムドメインの URL を指定できます。これにより、[OIDC 発行者識別子](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) の値にも影響します。 | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 本番用にカスタムドメインの URL を指定できます（例：`ADMIN_ENDPOINT=https://admin.domain.com`）。これにより、管理コンソールのリダイレクト URI の値にも影響します。 | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | ユーザー名が大文字小文字を区別するかどうかを指定します。この値を変更する際は注意が必要です。変更は既存のデータベースデータを自動的に調整しないため、手動での管理が必要です。 | +デフォルト値では、`protocol` は HTTPS 設定に応じて `http` または `https` となります。 + +| Key | デフォルト値 | 型 | 説明 | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto が実行される環境の種類。 | +| PORT | `3001` | `number` | Logto がリッスンするローカルポート。 | +| ADMIN_PORT | `3002` | `number` | Logto 管理コンソールがリッスンするローカルポート。 | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 管理コンソール用のポートを無効にするには `1` または `true` を設定します。`ADMIN_ENDPOINT` が未設定の場合、管理コンソールが完全に無効になります。 | +| DB_URL | N/A | `string` | Logto データベース用の [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 | +| HTTPS_CERT_PATH | `undefined` | string | undefined | 詳細は [HTTPS の有効化](#enabling-https) を参照してください。 | +| HTTPS_KEY_PATH | `undefined` | string | undefined | 同上。 | +| TRUST_PROXY_HEADER | `false` | `boolean` | 同上。 | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | オンラインテストや本番環境用にカスタムドメインの URL を指定できます。これにより [OIDC 発行者 (Issuer) 識別子](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) の値も影響を受けます。 | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 本番環境用にカスタムドメインの URL を指定できます（例：`ADMIN_ENDPOINT=https://admin.domain.com`）。これにより管理コンソールのリダイレクト URI の値も影響を受けます。 | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | ユーザー名が大文字小文字を区別するかどうかを指定します。この値を変更する際は注意してください。既存のデータベースデータは自動的に調整されないため、手動で管理する必要があります。 | +| SECRET_VAULT_KEK | `undefined` | `string` | [Secret Vault](/secret-vault) でデータ暗号化キー (DEK) を暗号化するためのキー暗号化キー (KEK)。Secret Vault を正しく機能させるために必須です。base64 エンコードされた文字列である必要があります。AES-256（32 バイト）推奨。例：`crypto.randomBytes(32).toString('base64')` | ### HTTPS の有効化 {#enabling-https} -#### Node を使用する {#using-node} +#### Node を使用する場合 {#using-node} -Node はネイティブに HTTPS をサポートしています。Node 経由で HTTPS を有効にするには、`HTTPS_CERT_PATH` と `HTTPS_KEY_PATH` の **両方** を提供します。 +Node はネイティブで HTTPS をサポートしています。Node で HTTPS を有効にするには、`HTTPS_CERT_PATH` と `HTTPS_KEY_PATH` の **両方** を指定してください。 -`HTTPS_CERT_PATH` は HTTPS 証明書のパスを示し、`HTTPS_KEY_PATH` は HTTPS キーのパスを示します。 +`HTTPS_CERT_PATH` は HTTPS 証明書のパス、`HTTPS_KEY_PATH` は HTTPS キーのパスを意味します。 -#### HTTPS プロキシを使用する {#using-a-https-proxy} +#### HTTPS プロキシを使用する場合 {#using-a-https-proxy} -もう一つの一般的な方法は、Node の前に HTTPS プロキシを配置することです（例：Nginx）。 +もう一つの一般的な方法は、Node の前段に HTTPS プロキシ（例：Nginx）を配置することです。 -この場合、プロキシヘッダーフィールドを信頼するかどうかを示す `TRUST_PROXY_HEADER` を `true` に設定することをお勧めします。Logto はこの値を [Koa アプリ設定](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings) に渡します。 +この場合、`TRUST_PROXY_HEADER` を `true` に設定することを推奨します。これはプロキシヘッダーフィールドを信頼するかどうかを示します。Logto はこの値を [Koa アプリ設定](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings) に渡します。 -このフィールドを設定するタイミングについては、[TLS オフロードプロキシの信頼](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) を参照してください。 +このフィールドを設定するタイミングについては [TLS オフロードプロキシの信頼](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) を参照してください。 ## データベース設定 {#database-configs} -多くの環境変数を管理することは効率的で柔軟ではないため、一般的な設定のほとんどはデータベーステーブル `logto_configs` に保存されています。 +環境変数が多すぎると管理が非効率かつ柔軟性に欠けるため、一般的な設定の多くはデータベーステーブル `logto_configs` に保存されています。 -このテーブルはシンプルなキー・バリューのストレージであり、キーは次のように列挙されます： +このテーブルはシンプルなキー・バリュー型ストレージであり、キーは次のように列挙可能です： -| Key | Type | Description | -| ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -| oidc.cookieKeys | string[] | [署名クッキーキー](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys) の文字列配列。 | -| oidc.privateKeys | string[] | [OIDC JWT 署名](https://openid.net/specs/openid-connect-core-1_0.html#Signing) のための秘密鍵コンテンツの文字列配列。 | +| Key | 型 | 説明 | +| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------- | +| oidc.cookieKeys | string[] | [署名クッキーキー](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys) の文字列配列。 | +| oidc.privateKeys | string[] | [OIDC JWT 署名](https://openid.net/specs/openid-connect-core-1_0.html#Signing) 用の秘密鍵内容の文字列配列。 | -### サポートされている秘密鍵の種類 {#supported-private-key-types} +### サポートされている秘密鍵タイプ {#supported-private-key-types} -- EC (P-256, secp256k1, P-384, および P-521 曲線) +- EC（P-256、secp256k1、P-384、P-521 曲線） - RSA -- OKP (Ed25519, Ed448, X25519, X448 サブタイプ) +- OKP（Ed25519、Ed448、X25519、X448 サブタイプ） diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index 63999661912..90b34234e2a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -11,13 +11,13 @@ import Oidc from '@site/docs/connectors/assets/icons/sso-oidc.svg'; import Okta from '@site/docs/connectors/assets/icons/sso-okta.svg'; import Saml from '@site/docs/connectors/assets/icons/sso-saml.svg'; -Logto の [シングルサインオン (SSO) ソリューション](/end-user-flows/enterprise-sso) は、エンタープライズクライアント向けのアクセス管理を簡素化します。エンタープライズ SSO コネクターは、さまざまなエンタープライズクライアント向けに SSO を有効化するために不可欠です。 +Logto の [エンタープライズシングルサインオン (SSO) ソリューション](/end-user-flows/enterprise-sso) は、エンタープライズクライアント向けのアクセス管理を簡素化します。エンタープライズ SSO コネクターは、さまざまなエンタープライズクライアント向けに SSO を有効化するために不可欠です。 -これらのコネクターは、サービスとエンタープライズのアイデンティティプロバイダー (IdP) 間の認証 (Authentication) プロセスを円滑にします。Logto は [SP-initiated SSO](/end-user-flows/enterprise-sso/sp-initiated-sso) と [IdP-initiated SSO](/end-user-flows/enterprise-sso/idp-initiated-sso) の両方をサポートしており、組織メンバーが既存の会社認証情報を使ってサービスへアクセスできるようになり、セキュリティと生産性が向上します。 +これらのコネクターは、サービスとエンタープライズのアイデンティティプロバイダー (IdP) 間の認証 (Authentication) プロセスを円滑にします。Logto は [SP-initiated SSO](/end-user-flows/enterprise-sso/sp-initiated-sso) と [IdP-initiated SSO](/end-user-flows/enterprise-sso/idp-initiated-sso) の両方をサポートしており、組織メンバーが既存の会社の認証情報を使ってサービスへアクセスできるようになり、セキュリティと生産性が向上します。 ## エンタープライズコネクター \{#enterprise-connectors} -Logto は、主要なエンタープライズアイデンティティプロバイダー向けのプリビルドコネクターを提供しており、迅速な統合が可能です。カスタム要件には、[OpenID Connect (OIDC)](https://auth.wiki/openid-connect) および [SAML](https://auth.wiki/saml) プロトコルによる統合もサポートしています。 +Logto は、主要なエンタープライズアイデンティティプロバイダー向けの事前構築済みコネクターを提供し、迅速な統合を実現します。カスタム要件には、[OpenID Connect (OIDC)](https://auth.wiki/openid-connect) および [SAML](https://auth.wiki/saml) プロトコルによる統合もサポートしています。 ### 主要なエンタープライズコネクター \{#popular-enterprise-connectors} @@ -87,24 +87,25 @@ Logto は、主要なエンタープライズアイデンティティプロバ 1. 次の場所へ移動します：コンソール > エンタープライズ SSO。 2. 「エンタープライズコネクターを追加」ボタンをクリックし、コネクタータイプを選択します。 -3. 一意の名前を入力します（例：Acme 社向け Okta）。 +3. 一意の名前を入力します（例：Acme Company 用 Okta）。 4. 「接続」タブで IdP との接続を設定します。各コネクタータイプのガイドを上記でご確認ください。 -5. 「体験」タブで SSO 体験および **メールドメイン** をカスタマイズします。 -6. SAML エンタープライズコネクターの場合、「IdP-initiated SSO」タブで IdP-initiated SSO を有効化することは任意です。[ガイドを参照](/end-user-flows/enterprise-sso/idp-initiated-sso) してください。 +5. 「体験」タブで SSO 体験や **メールドメイン** をカスタマイズします。 +6. SAML エンタープライズコネクターの場合、「IdP-initiated SSO」タブで IdP-initiated SSO を有効化することができます（任意）。詳細は [ガイド](/end-user-flows/enterprise-sso/idp-initiated-sso) をご参照ください。 7. 変更を保存します。 以下の設定にご注意ください： -- **メールドメイン**：ユーザーが入力したメールのドメインが、いずれかのエンタープライズ SSO コネクターの「エンタープライズメールドメイン」欄に含まれている場合、そのユーザーは該当 SSO コネクターのサインイン URL へリダイレクトされます。 +- **メールドメイン**：ユーザーが入力したメールのドメインが、いずれかのエンタープライズ SSO コネクターの「エンタープライズメールドメイン」欄に含まれている場合、そのユーザーは該当する SSO コネクターのサインイン URL へリダイレクトされます。 :::note - SSO コネクターで関連するメールドメインを設定した後、そのドメインのメールでサインインするユーザーは [SSO サインイン](/end-user-flows/enterprise-sso) を強制されることにご注意ください。 + SSO コネクターで関連するメールドメインを設定した後、そのドメインに属するメールでサインインするユーザーは [SSO サインイン](/end-user-flows/enterprise-sso) を強制される点にご注意ください。 - つまり、SSO コネクターで設定されていないドメインのメールのみが「メール＋認証コード」または「メール＋パスワード」でサインインできます（これら 2 つのサインイン方法がサインイン体験で有効化されている場合）。 + つまり、SSO コネクターで設定されていないドメインのメールのみが「メール＋認証コード」または「メール＋パスワード」でサインインできます（これらのサインイン方法がサインイン体験で有効化されている場合）。 ::: - **ユーザープロファイルの同期**：ユーザープロファイル情報（例：アバター、名前）をいつ同期するか選択します。デフォルトは「初回サインイン時のみ同期」です。「毎回サインイン時に常に同期」も選択できますが、カスタムユーザーデータが上書きされる可能性があります。 -- **表示情報**：コネクターの表示名やロゴをカスタマイズできます。同じメールドメインに複数のコネクターが紐付いている場合に便利です。ユーザーは SSO コネクターボタンのリストから希望する IdP を選択し、その後 IdP のログインページへリダイレクトされます。 +- **トークン保存の有効化**：OIDC エンタープライズコネクターでは、ユーザーがエンタープライズ IdP でサインインした際に、アクセス トークンおよびリフレッシュ トークンを Logto の [Secret Vault](/secret-vault) に安全に保存するトークン保存を有効化できます。これにより、ユーザーが再認証することなく、アプリケーションがユーザーに代わってサードパーティ API へアクセスできます。詳細は [フェデレーテッドトークン保存](/secret-vault/federated-token-set) をご覧ください。 +- **表示情報**：コネクターの表示名やロゴをカスタマイズできます。これは、同じメールドメインに複数のコネクターが紐付いている場合に非常に便利です。ユーザーは、IdP ログインページへリダイレクトされる前に、SSO コネクターボタンのリストから希望する IdP を選択します。 ## エンタープライズ SSO の有効化 \{#enabling-enterprise-sso} @@ -112,13 +113,13 @@ Logto は、主要なエンタープライズアイデンティティプロバ 2. 「エンタープライズ SSO」トグルを有効化します。 3. 変更を保存します。 -有効化すると、サインインページに「シングルサインオン」ボタンが表示されます。SSO 有効なメールドメインを持つエンタープライズユーザーは、エンタープライズアイデンティティプロバイダー (IdP) を使ってサービスへアクセスできます。SSO ユーザー体験の詳細は、ユーザーフロー：[エンタープライズ SSO](/end-user-flows/enterprise-sso) をご参照ください。 +有効化すると、サインインページに「シングルサインオン」ボタンが表示されます。SSO 対応メールドメインを持つエンタープライズユーザーは、エンタープライズアイデンティティプロバイダー (IdP) を使ってサービスへアクセスできます。SSO ユーザー体験の詳細は、ユーザーフロー：[エンタープライズ SSO](/end-user-flows/enterprise-sso) をご参照ください。 ## ジャストインタイムで組織へ \{#just-in-time-to-organization} -Logto では、[ジャストインタイム (JIT) プロビジョニング](https://auth.wiki/jit-provisioning) は、ユーザーが初めてシステムにサインインする際に、組織メンバーシップやロールを自動割り当てするプロセスです。 +Logto では、[ジャストインタイム (JIT) プロビジョニング](https://auth.wiki/jit-provisioning) は、ユーザーが初めてシステムへサインインする際に、組織メンバーシップやロールを自動で割り当てるプロセスです。 -Logto は、組織内で SSO コネクターの JIT プロビジョニングを設定するためのエントリーポイントを提供しています。[リファレンス](/organizations/just-in-time-provisioning) をご覧ください。 +Logto は、組織内で SSO コネクターの JIT プロビジョニングを設定するためのエントリーポイントを提供しています。詳細は [リファレンス](/organizations/just-in-time-provisioning) をご覧ください。 ## よくある質問 \{#faqs} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/connectors/social.mdx index 668ee14d3d2..85aa19262eb 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,15 +7,15 @@ sidebar_position: 3 # ソーシャルコネクター -Logto を使用して [ソーシャルログイン](/end-user-flows/sign-up-and-sign-in/social-sign-in) を有効にすることで、ユーザーのオンボーディングを簡素化し、コンバージョン率を向上させましょう。ユーザーは既存のソーシャルメディアアカウントを使用して迅速かつ安全にサインインでき、パスワードの作成や複雑な登録フローが不要になります。Logto は、さまざまな事前構築されたソーシャルコネクターを提供し、最大限の柔軟性を持つカスタム統合をサポートしています。 +Logto で [ソーシャルログイン](/end-user-flows/sign-up-and-sign-in/social-sign-in) を有効にすることで、ユーザーのオンボーディングを簡素化し、コンバージョン率を向上させましょう。ユーザーは既存のソーシャルメディアアカウントを使って迅速かつ安全にサインインできるため、パスワードの作成や複雑な登録フローが不要になります。Logto は多様なプリビルトのソーシャルコネクターを提供し、最大限の柔軟性のためにカスタム統合もサポートしています。 ## ソーシャルコネクターを選択する \{#choose-your-social-connectors} -Logto は、2 種類のソーシャルコネクターを提供しています： +Logto では、2 種類のソーシャルコネクターを提供しています： ### 人気のソーシャルコネクター \{#popular-social-connectors} -Logto は、すぐに使用できる人気のソーシャルプラットフォーム用に事前設定されたコネクターを提供しています。 +Logto は、人気のソーシャルプラットフォーム向けに事前構成済みのコネクターを提供しており、すぐに利用できます。 ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'Google コネクターは、アプリケーションが Google の OAuth 2.0 認証システムを使用するための簡潔な方法を提供します。', + description: 'Google コネクターは、アプリケーションで Google の OAuth 2.0 認証システムを簡潔に利用できる方法を提供します。', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'Facebook コネクターは、アプリケーションが Facebook の OAuth 2.0 認証システムを使用するための方法を提供します。', + description: 'Facebook コネクターにより、アプリケーションで Facebook の OAuth 2.0 認証システムを利用できます。', customProps: { icon: , } @@ -52,7 +52,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Apple', href: '/integrations/apple', - description: 'Apple ソーシャルサインインのための公式 Logto コネクター。', + description: 'Apple ソーシャルサインイン用の公式 Logto コネクターです。', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'Microsoft Azure AD コネクターは、アプリケーションが Azure の OAuth 2.0 認証システムを使用するための簡潔な方法を提供します。', + description: 'Microsoft Azure AD コネクターは、アプリケーションで Azure の OAuth 2.0 認証システムを簡潔に利用できる方法を提供します。', customProps: { icon: , } @@ -70,7 +70,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'GitHub', href: '/integrations/github', - description: 'GitHub ソーシャルサインインのための公式 Logto コネクター。', + description: 'GitHub ソーシャルサインイン用の公式 Logto コネクターです。', customProps: { icon: , } @@ -79,7 +79,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Discord', href: '/integrations/discord', - description: 'Discord コネクターは、アプリケーションが Discord を認可システムとして使用するための方法を提供します。', + description: 'Discord コネクターは、アプリケーションで Discord を認可システムとして利用する方法を提供します。', customProps: { icon: , } @@ -88,11 +88,11 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -[さらに詳しく](/integrations)... +[さらに詳しくはこちら](/integrations)... ### ソーシャルコネクターをカスタマイズする \{#customize-your-social-connectors} -カスタム要件には、OAuth 2.0 および OIDC (OpenID Connect) 標準を利用して、好みのプロバイダーを統合します。 +カスタム要件がある場合は、OAuth 2.0 および OIDC (OpenID Connect) 標準を利用して、希望するプロバイダーと統合できます。 ```mdx-code-block , } @@ -110,7 +110,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'OIDC', href: '/integrations/oidc', - description: 'OAuth 2.0 プロトコルのための公式 Logto コネクター。', + description: 'OAuth 2.0 プロトコル用の公式 Logto コネクターです。', customProps: { icon: , } @@ -119,30 +119,33 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -標準のコネクターが特定の要件を満たさない場合は、[お問い合わせ](https://logto.productlane.com/roadmap)ください。OSS ユーザーの場合、要件が緊急であれば [コネクターを実装する (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) ことができます。私たちは常に [貢献](/logto-oss/contribution) を歓迎しています。あなたの努力が、同じニーズを持つ他のコミュニティメンバーを助けるかもしれません。 +標準コネクターが要件を満たさない場合は、[お問い合わせ](https://logto.productlane.com/roadmap) ください。OSS ユーザーの場合、要件が急ぎの場合は [コネクターの実装 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) も可能です。常に [コントリビューション](/logto-oss/contribution) を歓迎しています。あなたの取り組みが同じニーズを持つ他のコミュニティメンバーの助けになるかもしれません。 ## 設定手順 \{#configuration-steps} 1. コンソール > コネクター > ソーシャルコネクター に移動します。 -2. 「ソーシャルコネクターを追加」をクリックし、希望のタイプを選択します。 -3. README ガイドに従い、必要なフィールドを入力し、設定をカスタマイズします。 -4. 「保存して完了」をクリックして終了します。 +2. 「ソーシャルコネクターを追加」をクリックし、希望するタイプを選択します。 +3. README ガイドに従い、必要な項目を入力し設定をカスタマイズします。 +4. 「保存して完了」をクリックします。 5. ソーシャルサインインを開始してコネクターをテストします。 -次の設定に注意してください： +次の設定にご注意ください： -- **アイデンティティプロバイダー名**：各ソーシャルコネクターには、ユーザーのアイデンティティを区別するための一意のアイデンティティプロバイダー (IdP) 名があります。一般的なコネクターは固定された IdP 名を使用しますが、カスタムコネクターには一意の値が必要です。詳細については、[IdP 名](/connectors/connector-data-structure#target-identity-provider-name) を参照してください。 -- **ユーザープロファイルの同期**：[ユーザープロファイル情報](/user-management/user-data#social-identities)（例：アバター、ユーザー名）を同期するタイミングを選択します。デフォルトは「登録時のみ同期」です。「各サインイン時に同期」は代替オプションですが、カスタムユーザーデータを上書きする可能性があります。 +- **アイデンティティプロバイダー名**：各ソーシャルコネクターには、ユーザーアイデンティティを区別するための一意のアイデンティティプロバイダー (IdP) 名があります。一般的なコネクターは固定の IdP 名を使用しますが、カスタムコネクターは一意の値が必要です。詳細は [IdP 名について](/connectors/connector-data-structure#target-identity-provider-name) をご覧ください。 +- **ユーザープロファイルの同期**：[ユーザープロファイル情報](/user-management/user-data#social-identities)（例：アバター、ユーザー名）をいつ同期するか選択できます。デフォルトは「登録時のみ同期」です。「サインインごとに同期」も選択できますが、カスタムユーザーデータが上書きされる場合があります。 +- **トークン保存の有効化**：対応するソーシャルコネクターでは、ユーザーがソーシャルプロバイダーでサインインした際にアクセス トークンおよびリフレッシュ トークンを Logto の [シークレットボールト](/secret-vault) に安全に保存できます。これにより、アプリケーションはユーザーに再認証を求めることなく、ユーザーの代理でサードパーティ API にアクセスできます。詳細は [フェデレーテッドトークン保存](/secret-vault/federated-token-set) をご覧ください。 -## ソーシャルサインインを有効にする \{#enable-social-sign-in} +## ソーシャルサインインを有効化する \{#enable-social-sign-in} -ソーシャルコネクターを正常に作成したら、サインイン体験でソーシャルログインボタン（例：Google で続行）として有効にできます。 +ソーシャルコネクターを作成したら、サインイン体験の中でソーシャルログインボタン（例：Google で続行）として有効化できます。 -{/* eslint-disable-next-line prettier/prettier */} -1. コンソール > サインイン体験 > サインアップとサインイン に移動します。 -2. （オプション）ソーシャルログインのみが必要な場合は、サインアップ識別子に「該当なし」を選択します。 +1. + コンソール > サインイン体験 > サインアップとサインイン + + に移動します。 +2. （任意）ソーシャルログインのみを利用する場合は、サインアップ識別子に「該当なし」を選択します。 3. 設定済みのソーシャルコネクターを「ソーシャルサインイン」セクションに追加します。 4. 必要に応じてコネクターの順序を変更します。 -5. 「変更を保存」をクリックし、「ライブプレビュー」をテストします。 +5. 「変更を保存」をクリックし、「ライブプレビュー」でテストします。 -詳細については、[ソーシャルサインイン](/end-user-flows/sign-up-and-sign-in/social-sign-in) を参照してください。 +詳細は [ソーシャルサインイン](/end-user-flows/sign-up-and-sign-in/social-sign-in) をご覧ください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index 31531eb66fe..7ba0143fb3f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -12,18 +12,63 @@ import Integration from './_integration.mdx'; # Facebook を使用してソーシャルログインを設定する -Facebook ソーシャルサインインのための公式 Logto コネクター。 +Facebook OAuth 2.0 認証 (Authentication) システムを統合し、「Facebook でサインイン」、アカウント連携、Facebook API への安全なアクセスを実現します。 ## はじめに \{#get-started} -Facebook コネクターは、あなたのアプリケーションが Facebook の OAuth 2.0 認証 (Authentication) システムを使用するための簡潔な方法を提供します。 +Facebook コネクターを利用すると、OAuth 2.0 統合によりアプリケーションで以下が可能になります： + +- 「Facebook でサインイン」認証 (Authentication) の追加 +- ユーザーアカウントを Facebook アイデンティティに連携 +- Facebook からユーザープロフィール情報の同期 +- Logto Secret Vault に安全に保存されたトークンを通じて Facebook API へアクセスし、自動化タスクを実行（例：スレッドへの返信、アプリ内でのコンテンツや動画の公開） + +これらの認証 (Authentication) 機能を設定するには、まず Logto で Facebook コネクターを作成します： + +1. [Logto > コネクター > ソーシャルコネクター](https://cloud.logto.io/to/connectors/social) にアクセスします。 +2. **ソーシャルコネクターを追加** をクリックし、**Facebook** を選択、**次へ** をクリックし、手順に従って統合を完了します。 -## 参考文献 \{#references} +## Facebook コネクターの活用 \{#utilize-the-facebook-connector} + +Facebook コネクターを作成し Facebook と接続したら、エンドユーザーのフローに組み込むことができます。ニーズに合わせてオプションを選択してください： + +### 「Facebook でサインイン」を有効化 \{#enable-sign-in-with-facebook} + +1. Logto コンソールで サインイン体験 > サインアップとサインイン に移動します。 +2. **ソーシャルサインイン** セクションで Facebook コネクターを追加し、ユーザーが Facebook で認証 (Authentication) できるようにします。 + +[ソーシャルサインイン体験](/end-user-flows/sign-up-and-sign-in/social-sign-in) について詳しくはこちら。 + +### Facebook アカウントの連携・解除 \{#link-or-unlink-a-facebook-account} + +Account API を利用して、サインイン中のユーザーが Facebook アカウントを連携または解除できるカスタムアカウントセンターをアプリ内に構築できます。[Account API チュートリアルを参照](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Facebook コネクターは、ソーシャルサインインを有効にせず、アカウント連携や API アクセス専用として有効化することも可能です。 +::: + +### Facebook API へのアクセスとアクションの実行 \{#access-facebook-api-and-perform-actions} + +アプリケーションは Secret Vault から保存された Facebook アクセストークンを取得し、Facebook API を呼び出してバックエンドタスクを自動化できます（例：コンテンツの公開や投稿管理など）。API アクセス用の保存トークン取得ガイドを参照してください。 + +## ユーザーの Facebook アイデンティティ管理 \{#manage-user-s-facebook-identity} + +ユーザーが Facebook アカウントを連携した後、管理者は Logto コンソールでその接続を管理できます： + +1. ユーザー管理 に移動し、該当ユーザーのプロフィールを開きます。 +2. **ソーシャル接続** セクションで Facebook 項目を見つけ、**管理** をクリックします。 +3. このページで管理者は、ユーザーの Facebook 接続を管理し、Facebook アカウントから付与・同期されたすべてのプロフィール情報やアクセストークンの状態を確認できます。 + +:::note +Facebook のアクセストークン応答には特定のスコープ情報が含まれていないため、Logto でユーザーが付与した権限 (Permissions) の一覧を直接表示することはできません。ただし、ユーザーが認可 (Authorization) 時に要求されたスコープに同意していれば、アプリケーションは Facebook API へアクセスする際に対応する権限 (Permissions) を持ちます。必要なスコープは Facebook Developer Console と Logto の両方で正確に設定することを推奨します。 +::: + +## 参考 \{#reference} + +Facebook for Developers - ドキュメント -- [Facebook Login - Documentation - Facebook for Developers](https://developers.facebook.com/docs/facebook-login/) - - [Manually Build a Login Flow](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [Permissions Guide](https://developers.facebook.com/docs/facebook-login/guides/permissions) +Facebook ログイン ドキュメント diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index 3bbd7142a74..7eca78c7c91 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,54 +1,100 @@ -### Facebook デベロッパーアカウントを登録する \{#register-a-facebook-developer-account} +## ステップ 1: Facebook App Dashboard でアプリをセットアップする \{#step-1-set-up-an-app-on-facebook-app-dashboard} -まだアカウントを持っていない場合は、[Facebook デベロッパーとして登録](https://developers.facebook.com/docs/development/register/) してください。 +Facebook を認証 (Authentication) プロバイダーとして利用する前に、Facebook デベロッパープラットフォームでアプリをセットアップし、OAuth 2.0 資格情報を取得する必要があります。 -### Facebook アプリを設定する \{#set-up-a-facebook-app} +1. まだアカウントがない場合は、 [Facebook デベロッパーとして登録](https://developers.facebook.com/docs/development/register/) してください。 +2. [アプリ](https://developers.facebook.com/apps) ページにアクセスします。 +3. 既存のアプリをクリックするか、必要に応じて [新しいアプリを作成](https://developers.facebook.com/docs/development/create-an-app) します。 -1. [Apps](https://developers.facebook.com/apps) ページにアクセスします。 -2. 既存のアプリをクリックするか、必要に応じて[新しいアプリを作成](https://developers.facebook.com/docs/development/create-an-app) します。 - - 選択する [アプリタイプ](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types) は任意ですが、_Facebook Login_ プロダクトを含んでいる必要があります。 -3. アプリダッシュボードページで、「Add a product」セクションまでスクロールし、「Facebook Login」カードの「Set up」ボタンをクリックします。 -4. Facebook Login クイックスタートページをスキップし、サイドバー -> 「Products」 -> 「Facebook Login」 -> 「Settings」をクリックします。 -5. Facebook Login 設定ページで、「Valid OAuth Redirect URIs」フィールドに `${your_logto_origin}/callback/${connector_id}` を入力します。`connector_id` は Logto 管理コンソールのコネクター詳細ページの上部バーにあります。例： - - 本番環境の場合：`https://logto.dev/callback/${connector_id}` - - ローカル環境でのテストの場合：`https://localhost:3001/callback/${connector_id}` -6. 右下隅の「Save changes」ボタンをクリックします。 +:::tip +ユースケースは、アプリが Meta とどのようにやり取りするかの主要な方法であり、アプリで利用可能な API、機能、権限、プロダクトを決定します。ソーシャル認証 (Authentication) のみ（メールアドレスと public_profile の取得）が必要な場合は「Authentication and request data from users with Facebook Login」を選択してください。Facebook API へのアクセスが必要な場合は、希望するユースケースを選択してください。ほとんどのユースケースは、アプリ作成後に「Facebook Login for business」の統合もサポートしています。 +::: -## コネクター JSON を作成する \{#compose-the-connector-json} +4. アプリ作成後、アプリダッシュボードページで **Use cases > Facebook Login > Settings** または **Facebook Login for business > Settings** に移動します。 +5. **Valid OAuth Redirect URIs** に Logto の **Callback URI** を入力します（Logto の Facebook コネクターからコピーしてください）。ユーザーが Facebook でサインインした後、ここに認可コード付きでリダイレクトされ、Logto が認証 (Authentication) を完了します。 +6. **Use cases** に移動し、ユースケースの **Customize** をクリックしてスコープを追加します。Logto で Facebook サインインを実装するには `email` と `public_profile` の追加を推奨します（必須）。 -1. Facebook アプリダッシュボードページで、サイドバー -> 「Settings」 -> 「Basic」をクリックします。 -2. パネルに「App ID」と「App secret」が表示されます。 -3. App secret 入力ボックスの「Show」ボタンをクリックして、その内容をコピーします。 -4. Logto コネクター設定を入力します： - - `clientId` フィールドに _App ID_ の文字列を入力します。 - - `clientSecret` フィールドに _App secret_ の文字列を入力します。 - - `scope` フィールドに、カンマまたはスペースで区切られた [権限](https://developers.facebook.com/docs/permissions/reference) のリストを文字列で入力します。スコープを指定しない場合、デフォルトのスコープは `email,public_profile` です。 +## ステップ 2: クライアント資格情報で Logto コネクターをセットアップする \{#step-2-set-up-logto-connector-with-client-credentials} -## Facebook のテストユーザーでサインインをテストする \{#test-sign-in-with-facebooks-test-users} +1. Facebook App Dashboard で、サイドバーの **App settings > Basic** をクリックします。 +2. パネルに **App ID** と **App secret** が表示されます。 +3. App secret 入力欄の横にある **Show** ボタンをクリックして内容を表示し、コピーします。 +4. Logto の Facebook コネクター設定を行います： + - `clientId` フィールドに **App ID** を入力します。 + - `clientSecret` フィールドに **App secret** を入力します。 + - Logto で **Save and Done** をクリックし、アイデンティティシステムと Facebook を接続します。 -開発およびライブの [アプリモード](https://developers.facebook.com/docs/development/build-and-test/app-modes) の両方で、関連するアプリでのサインインをテストするために、テスト、開発者、および管理者ユーザーのアカウントを使用できます。 +## ステップ 3: スコープを設定する \{#step-3-configure-scopes} -また、アプリを直接 [ライブにする](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode) ことで、任意の Facebook ユーザーがアプリでサインインできるようにすることもできます。 +スコープは、アプリがユーザーから要求する権限を定義し、Facebook アカウントからどのプライベートデータにアクセスできるかを制御します。 -- アプリダッシュボードページで、サイドバー -> 「Roles」 -> 「Test Users」をクリックします。 -- 「Create test users」ボタンをクリックしてテストユーザーを作成します。 -- 既存のテストユーザーの「Options」ボタンをクリックすると、「名前とパスワードの変更」などの操作が表示されます。 +### Facebook App Dashboard でスコープを設定する \{#configure-scopes-in-facebook-app-dashboard} -## Facebook サインイン設定を公開する \{#publish-facebook-sign-in-settings} +1. **Facebook App Dashboard > Use cases** に移動し、**Customize** ボタンをクリックします。 +2. アプリが必要とするスコープのみを追加します。ユーザーは Facebook の同意画面でこれらの権限を確認し、承認します： + - **認証 (Authentication) 用（必須）**：`email` と `public_profile` + - **API アクセス用（任意）**：アプリが必要とする追加スコープ（例：Threads API へのアクセスには `threads_content_publish`、`threads_read_replies` など）。利用可能なサービスは [Meta Developer Documentation](https://developers.facebook.com/docs/) を参照してください。 -通常、[開発モード](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode) では、テスト、管理者、および開発者ユーザーのみが関連するアプリでサインインできます。 +### Logto でスコープを設定する \{#configure-scopes-in-logto} -本番環境で通常の Facebook ユーザーがアプリでサインインできるようにするには、アプリタイプに応じて、Facebook アプリを _[ライブモード](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_ に切り替える必要があるかもしれません。例えば、純粋な _ビジネスタイプ_ のアプリには「ライブ」スイッチボタンがありませんが、使用を妨げることはありません。 +ニーズに応じて、以下のいずれかの方法を選択してください： -1. Facebook アプリダッシュボードページで、サイドバー -> 「Settings」 -> 「Basic」をクリックします。 -2. 必要に応じて、パネルの「Privacy Policy URL」と「User data deletion」フィールドを入力します。 -3. 右下隅の「Save changes」ボタンをクリックします。 -4. アプリのトップバーで「Live」スイッチボタンをクリックします。 +**オプション 1: 追加の API スコープが不要な場合** -## 設定タイプ \{#config-types} +- Logto の Facebook コネクターの `Scopes` フィールドを空欄のままにします。 +- デフォルトのスコープ `email public_profile` がリクエストされ、Logto が基本的なユーザー情報を正しく取得できます。 -| 名前 | タイプ | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**オプション 2: サインイン時に追加スコープをリクエストする場合** + +- 必要なすべてのスコープを **Scopes** フィールドにスペース区切りで入力します。 +- ここに入力したスコープがデフォルトを上書きするため、必ず認証 (Authentication) 用スコープ `email public_profile` も含めてください。 + +**オプション 3: 後からインクリメンタルスコープをリクエストする場合** + +- ユーザーがサインインした後、フェデレーテッドソーシャル認可 (Authorization) フローを再実行し、ユーザーの保存済みトークンセットを更新することで、必要に応じて追加スコープをリクエストできます。 +- これらの追加スコープは Logto の Facebook コネクターの `Scopes` フィールドに入力する必要はなく、Logto の Social Verification API を通じて実現できます。 + +これらの手順に従うことで、Logto Facebook コネクターはアプリに必要な権限のみをリクエストします。 + +:::tip +アプリが Facebook API へのアクセスやアクション実行のためにこれらのスコープをリクエストする場合は、Logto Facebook コネクターで **Store tokens for persistent API access** を有効にしてください。詳細は次のセクションを参照してください。 +::: + +## ステップ 4: 一般設定 \{#step-4-general-settings} + +Facebook への接続を妨げることはありませんが、エンドユーザーの認証 (Authentication) 体験に影響する可能性のある一般的な設定を紹介します。 + +### プロフィール情報の同期 \{#sync-profile-information} + +Facebook コネクターでは、ユーザー名やアバターなどのプロフィール情報の同期ポリシーを設定できます。以下から選択してください： + +- **サインアップ時のみ同期**：ユーザーが初めてサインインしたときにプロフィール情報を一度だけ取得します。 +- **サインイン時に常に同期**：ユーザーがサインインするたびにプロフィール情報を更新します。 + +### Facebook API へのアクセス用トークンの保存（任意） \{#store-tokens-to-access-facebook-apis-optional} + +Facebook API へのアクセスやユーザー認可によるアクション実行（ソーシャルサインインまたはアカウント連携経由）を行いたい場合、Logto は特定の API スコープを取得し、トークンを保存する必要があります。 + +1. 上記の手順に従って必要なスコープを追加します。 +2. Logto Facebook コネクターで **Store tokens for persistent API access** を有効にします。Logto は Facebook アクセストークンを Secret Vault に安全に保存します。 + +:::note +Facebook はリフレッシュトークンを提供していません。ただし、トークン保存が有効な場合、Logto はユーザー認証 (Authentication) 時に自動的に長期間有効なアクセストークン（60日間）をリクエストします。この期間中、ユーザーは手動でアクセストークンを取り消すことができますが、そうでなければ Facebook API へのアクセスに再認可は不要です。注意：`offline_access` を `Scope` フィールドに追加しないでください。エラーの原因となる場合があります。 +::: + +## ステップ 5: Facebook のテストユーザーでサインインをテストする（任意） \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +テスト、開発者、管理者ユーザーアカウントを使ってアプリでのサインインをテストできます。また、アプリを公開して任意の Facebook ユーザーがサインインできるようにすることも可能です。 + +1. Facebook App Dashboard で、サイドバーの **App roles > Test Users** をクリックします。 +2. **Create test users** ボタンをクリックしてテストユーザーを作成します。 +3. 既存のテストユーザーの **Options** ボタンをクリックすると、「名前とパスワードの変更」などの操作が可能です。 + +## ステップ 6: Facebook サインイン設定を公開する \{#step-6-publish-facebook-sign-in-settings} + +通常、テスト、管理者、開発者ユーザーのみがアプリでサインインできます。プロダクション環境で一般の Facebook ユーザーがアプリでサインインできるようにするには、アプリを公開する必要があります。 + +1. Facebook App Dashboard で、サイドバーの **Publish** をクリックします。 +2. 必要に応じて **Privacy Policy URL** と **User data deletion** フィールドを入力します。 +3. 右下の **Save changes** ボタンをクリックします。 +4. アプリ上部バーの **Live** スイッチボタンをクリックします。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index 3de5decd6e2..a02db2ac96f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -13,26 +13,75 @@ import Integration from './_integration.mdx'; # GitHub を使用してソーシャルログインを設定する -GitHub ソーシャルサインインのための公式 Logto コネクター。 +GitHub OAuth アプリを統合することで、「Sign-in with GitHub」、アカウント連携、および GitHub API への安全なアクセスが可能になります。 -## 始める \{#get-started} +## はじめに \{#get-started} -GitHub コネクターを使用すると、エンドユーザーは GitHub OAuth 2.0 認証 (Authentication) プロトコルを介して自分の GitHub アカウントを使用してアプリケーションにサインインできます。 +GitHub コネクターは OAuth 2.0 連携を可能にし、アプリケーションで次のことができます： + +- 「Sign-in with GitHub」認証 (Authentication) の追加 +- ユーザーアカウントを GitHub アイデンティティに連携 +- GitHub からユーザープロフィール情報を同期 +- Logto Secret Vault に安全に保存されたトークンを利用して GitHub API へアクセスし、自動化タスクを実行（例：GitHub issue の作成、アプリからリポジトリ管理） + +これらの認証 (Authentication) 機能を設定するには、まず Logto で GitHub コネクターを作成します： + +1. + Logto コンソール > コネクター > ソーシャルコネクター + + 移動します。 +2. **ソーシャルコネクターを追加** をクリックし、**GitHub** を選択、**次へ** をクリックし、ステップバイステップのチュートリアルに従って統合を完了します。 -## GitHub コネクターをテストする \{#test-github-connector} +## GitHub コネクターの活用 \{#utilize-the-github-connector} + +GitHub コネクターを作成し、GitHub との接続が完了したら、エンドユーザーのフローに組み込むことができます。ニーズに合わせてオプションを選択してください： + +### 「Sign-in with GitHub」を有効にする \{#enable-sign-in-with-github} + +1. Logto コンソールで サインイン体験 > サインアップとサインイン に移動します。 +2. **ソーシャルサインイン** セクションで GitHub コネクターを追加し、ユーザーが GitHub で認証 (Authentication) できるようにします。 + +[ソーシャルサインイン体験](/end-user-flows/sign-up-and-sign-in/social-sign-in) について詳しく学ぶ。 + +### GitHub アカウントの連携または解除 \{#link-or-unlink-a-github-account} + +Account API を利用して、サインイン済みユーザーが GitHub アカウントを連携または解除できるカスタムアカウントセンターをアプリ内に構築できます。[Account API チュートリアルに従う](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -これで完了です。GitHub コネクターが利用可能になったはずです。[サインイン体験でソーシャルコネクターを有効にする](/connectors/social-connectors/#enable-social-sign-in) のを忘れないでください。 +:::tip +GitHub コネクターは、ソーシャルサインインを有効にせず、アカウント連携や API アクセス専用として有効化することも可能です。 +::: -## 参考 \{#reference} +### GitHub API へのアクセスとアクションの実行 \{#access-github-apis-and-perform-actions} + +アプリケーションは Secret Vault から保存された GitHub アクセストークンを取得し、GitHub API を呼び出してバックエンドタスクを自動化できます（例：issue の作成、リポジトリ管理、ワークフローの自動化など）。API アクセス用の保存トークン取得ガイドを参照してください。 + +## ユーザーの GitHub アイデンティティ管理 \{#manage-user-s-github-identity} + +ユーザーが GitHub アカウントを連携した後、管理者は Logto コンソールでその接続を管理できます： + +1. Logto コンソール > ユーザー管理 + に移動し、ユーザープロフィールを開きます。 +2. **ソーシャル接続** の下で GitHub 項目を見つけ、**管理** をクリックします。 +3. このページで管理者は、ユーザーの GitHub 接続を管理し、GitHub アカウントから付与・同期されたすべてのプロフィール情報を確認し、アクセストークンの状態をチェックできます。 + +:::note +GitHub のアクセストークン応答には特定のスコープ情報が含まれていないため、Logto ではユーザーが付与した権限 (Permissions) の一覧を直接表示できません。ただし、ユーザーが認可 (Authorization) 時に要求されたスコープに同意していれば、アプリケーションは GitHub API へアクセスする際に対応する権限 (Permissions) を持ちます。 +::: + +## 参考資料 \{#reference} - GitHub - 開発者 - アプリ + GitHub 開発者ドキュメント - アプリについて - GitHub - 開発者 - アプリ - OAuth アプリの作成 + GitHub 開発者ドキュメント - OAuth アプリの作成 + + + + GitHub OAuth アプリのスコープに関するドキュメント diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index 1a8e6ec5255..9fd9e74fd59 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,36 +1,99 @@ -### GitHub アカウントでサインインする \{#sign-in-with-github-account} +## ステップ 1: GitHub で OAuth アプリを作成する \{#step-1-create-an-oauth-app-on-github} -[GitHub ウェブサイト](https://github.com/) にアクセスし、GitHub アカウントでサインインします。アカウントをお持ちでない場合は、新しいアカウントを登録することができます。 +GitHub を認証 (Authentication) プロバイダーとして利用する前に、GitHub で OAuth アプリを作成し、OAuth 2.0 の認証情報を取得する必要があります。 -### OAuth アプリを作成して設定する \{#create-and-configure-oauth-app} +1. [GitHub](https://github.com/) にアクセスし、アカウントでサインインします。必要に応じて新しいアカウントを作成してください。 +2. [設定 > 開発者設定 > OAuth apps](https://github.com/settings/developers) に移動します。 +3. **New OAuth App** をクリックして新しいアプリケーションを登録します： + - **Application name**：アプリの説明的な名前を入力します。 + - **Homepage URL**：アプリケーションのホームページ URL を入力します。 + - **Authorization callback URL**：Logto の GitHub コネクターから **Callback URI** をコピーし、ここに貼り付けます。ユーザーが GitHub でサインインした後、ここにリダイレクトされ、Logto が認証 (Authentication) を完了するための認可コードが渡されます。 + - **Application description**：（任意）アプリの簡単な説明を追加します。 +4. **Register application** をクリックして OAuth アプリを作成します。 -[OAuth アプリの作成](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) ガイドに従って、新しいアプリケーションを登録します。 +:::note +**Enable Device Flow** のチェックボックスはオフのままにすることを推奨します。なぜなら、GitHub でサインインするユーザーがモバイルデバイスを利用する場合、GitHub モバイルアプリで初回サインイン操作を確認する必要があるためです。多くの GitHub ユーザーは GitHub モバイルアプリをインストールしていないため、サインインフローが妨げられる可能性があります。エンドユーザーが GitHub モバイルアプリでサインインフローを確認することを想定している場合のみ有効にしてください。[デバイスフロー](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow) の詳細を参照してください。 -**Application name** に新しい OAuth アプリケーションの名前を付け、アプリの **Homepage URL** を入力します。**Application description** フィールドは空白のままにして、**Authorization callback URL** を `${your_logto_origin}/callback/${connector_id}` にカスタマイズできます。`connector_id` は Logto Admin Console のコネクター詳細ページの上部バーにあります。 +GitHub OAuth アプリのセットアップ詳細については [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) をご覧ください。 +::: -:::note +## ステップ 2: Logto コネクターを設定する \{#step-2-configure-your-logto-connector} + +GitHub で OAuth アプリを作成した後、詳細ページにリダイレクトされ、Client ID をコピーしたり、Client secret を生成できます。 + +1. GitHub OAuth アプリから **Client ID** をコピーし、Logto の `clientId` フィールドに貼り付けます。 +2. GitHub で **Generate a new client secret** をクリックして新しいシークレットを作成し、それをコピーして Logto の `clientSecret` フィールドに貼り付けます。 +3. Logto で **Save and Done** をクリックし、アイデンティティシステムと GitHub を接続します。 + +:::warning +Client secret は安全に保管し、クライアントサイドのコードで絶対に公開しないでください。GitHub の client secret は紛失した場合、復元できません。新しいものを生成する必要があります。 +::: + +## ステップ 3: スコープを設定する（任意） \{#step-3-configure-scopes-optional} + +スコープは、アプリがユーザーから要求する権限を定義し、GitHub アカウントからどのデータにアクセスできるかを制御します。 + +Logto の `Scopes` フィールドを使って、GitHub から追加の権限をリクエストできます。ニーズに応じて次のいずれかの方法を選択してください： + +### オプション 1: 追加の API スコープが不要な場合 \{#option-1-no-extra-api-scopes-needed} + +- Logto の GitHub コネクターの `Scopes` フィールドを空欄のままにします。 +- デフォルトのスコープ `read:user` がリクエストされ、Logto が基本的なユーザー情報（メール、名前、アバターなど）を正しく取得できるようになります。 -ログイン時に「The redirect_uri MUST match the registered callback URL for this application.」というエラーメッセージが表示された場合は、GitHub OAuth アプリの Authorization Callback URL と Logto アプリのリダイレクト URL を一致させることで問題を解決してください（もちろん、プロトコルも含めて）。 +### オプション 2: サインイン時に追加スコープをリクエストする \{#option-2-request-additional-scopes-at-sign-in} +- [GitHub OAuth アプリ用の全スコープ一覧](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) を参照し、アプリに必要なスコープのみ追加します。 +- 必要なスコープをすべて **Scopes** フィールドにスペース区切りで入力します。 +- ここに記載したスコープはデフォルトを上書きするため、必ず認証 (Authentication) 用スコープ `read:user` を含めてください。 +- よく使われる追加スコープ例： + - `repo`：プライベートリポジトリの完全な制御 + - `public_repo`：パブリックリポジトリへのアクセス + - `user:email`：ユーザーのメールアドレスへのアクセス + - `notifications`：通知へのアクセス +- すべてのスコープが正しく有効であることを確認してください。誤ったスコープやサポートされていないスコープを指定すると、GitHub から「Invalid scope」エラーが返されます。 + +### オプション 3: 後からインクリメンタルスコープをリクエストする \{#option-3-request-incremental-scopes-later} + +- ユーザーがサインインした後、必要に応じてフェデレーテッドソーシャル認可フローを再実行し、ユーザーの保存済みトークンセットを更新することで追加スコープをリクエストできます。 +- これらの追加スコープは Logto の GitHub コネクターの `Scopes` フィールドに記載する必要はなく、Logto の Social Verification API を通じて実現できます。 + +これらの手順に従うことで、Logto の GitHub コネクターはアプリに必要な権限のみをリクエストします。 + +:::tip +アプリがこれらのスコープを使って GitHub API にアクセスし操作を行う場合は、Logto GitHub コネクターで **Store tokens for persistent API access** を有効にしてください。詳細は次のセクションを参照してください。 ::: -**Enable Device Flow** の前のチェックボックスをチェックしないことをお勧めします。そうしないと、モバイルデバイスで GitHub にサインインするユーザーは、GitHub アプリで最初のサインインアクションを確認する必要があります。多くの GitHub ユーザーは、携帯電話に GitHub モバイルアプリをインストールしていないため、サインインフローがブロックされる可能性があります。エンドユーザーがサインインフローを確認することを期待している場合は、この提案を無視してください。[デバイスフロー](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow) の詳細を参照してください。 +## ステップ 4: 一般設定 \{#step-4-general-settings} + +GitHub への接続を妨げることはありませんが、エンドユーザーの認証 (Authentication) 体験に影響する一般的な設定をいくつか紹介します。 + +### プロフィール情報の同期 \{#sync-profile-information} -### OAuth アプリの管理 \{#managing-oauth-apps} +GitHub コネクターでは、ユーザー名やアバターなどのプロフィール情報の同期ポリシーを設定できます。次のいずれかを選択してください： -[OAuth アプリページ](https://github.com/settings/developers) にアクセスすると、既存の OAuth アプリを追加、編集、または削除できます。 -また、OAuth アプリの詳細ページで `Client ID` を見つけたり、`Client secrets` を生成したりすることもできます。 +- **サインアップ時のみ同期**：ユーザーが初めてサインインしたときにプロフィール情報を取得します。 +- **サインイン時に常に同期**：ユーザーがサインインするたびにプロフィール情報を更新します。 -### コネクターを設定する \{#configure-your-connector} +### GitHub API へのアクセス用トークンの保存（任意） \{#store-tokens-to-access-github-apis-optional} + +ユーザーの認可で GitHub API にアクセスし操作を行いたい場合（ソーシャルサインインやアカウント連携経由）、Logto は特定の API スコープを取得し、トークンを保存する必要があります。 + +1. 上記の手順に従って必要なスコープを追加します。 +2. Logto GitHub コネクターで **Store tokens for persistent API access** を有効にします。Logto は GitHub のアクセストークンを Secret Vault に安全に保存します。 + +:::note +このチュートリアルで説明しているように **GitHub OAuth アプリ** を利用する場合、GitHub からリフレッシュトークン (Refresh token) を取得することはできません。なぜなら、アクセストークンはユーザーが手動で取り消さない限り有効期限がないためです。そのため、`Scopes` フィールドに `offline_access` を追加する必要はありません。追加するとエラーになる場合があります。 + +アクセストークンに有効期限を設けたい場合やリフレッシュトークン (Refresh token) を利用したい場合は、代わりに **GitHub App** との連携を検討してください。[GitHub Apps と OAuth Apps の違い](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) をご覧ください。 +::: -前のセクションで説明した OAuth アプリの詳細ページから取得した _Client ID_ と _Client Secret_ を `clientId` と `clientSecret` フィールドに入力します。 +## ステップ 5: 統合のテスト（任意） \{#step-5-test-your-integration-optional} -`scope` は、スペースで区切られた [スコープ](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) のリストです。指定しない場合、スコープはデフォルトで `read:user` になります。 +本番運用前に、GitHub 連携をテストしましょう： -### 設定タイプ \{#config-types} +1. Logto の開発テナントでコネクターを利用します。 +2. ユーザーが GitHub でサインインできることを確認します。 +3. 正しいスコープがリクエストされているか確認します。 +4. トークンを保存している場合は API コールもテストします。 -| 名前 | タイプ | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +GitHub OAuth アプリは、どの GitHub ユーザーアカウントでもすぐに動作します。他のプラットフォームのようにテストユーザーやアプリ承認は不要です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index c24c0385cb6..825be290a80 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -3,7 +3,7 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: description: Google は主要な検索エンジン技術およびメールサービスプロバイダーです。 -tutorial_config_name: Google OAuth app +tutorial_config_name: Google OAuth アプリ --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -12,14 +12,70 @@ import Integration from './_integration.mdx'; # Google を使用してソーシャルログインを設定する -Google コネクターは、アプリケーションが Google の OAuth 2.0 認証 (Authentication) システムを使用するための簡潔な方法を提供します。 +Google OAuth 2.0 認証システムを統合し、「Google でサインイン」、アカウント連携、Google API への安全なアクセスを有効にします。 +## はじめに \{#get-started} + +Google コネクター (Connector) を利用すると、OAuth 2.0 統合によりアプリケーションで次のことが可能になります： + +- 「Google でサインイン」認証 (Authentication) の追加 +- ユーザーアカウントと Google アイデンティティの連携 +- Google からユーザープロフィール情報の同期 +- Logto Secret Vault に安全に保存されたトークンを通じて Google API へアクセスし、自動化タスクを実行（例：Google ドキュメントの編集、アプリ内でのカレンダーイベント管理） + +これらの認証 (Authentication) 機能を設定するには、まず Logto で Google コネクター (Connector) を作成します： + +1. + Logto コンソール > コネクター (Connector) > ソーシャルコネクター (Connector) + + にアクセスします。 +2. **ソーシャルコネクター (Connector) を追加** をクリックし、**Google** を選択、**次へ** をクリックし、ステップバイステップのチュートリアルに従って統合を完了します。 + -## 参考文献 \{#references} +## Google コネクター (Connector) の活用 \{#utilize-the-google-connector} + +Google コネクター (Connector) を作成し、Google と接続したら、エンドユーザーのフローに組み込むことができます。ニーズに合ったオプションを選択してください： + +### 「Google でサインイン」を有効にする \{#enable-sign-in-with-google} + +1. Logto コンソールで サインイン体験 > サインアップとサインイン に移動します。 +2. **ソーシャルサインイン** セクションで Google コネクター (Connector) を追加し、ユーザーが Google で認証 (Authentication) できるようにします。 +3. 必要に応じて、サインインおよびサインアップページで **Google One Tap** を有効にし、スムーズな認証 (Authentication) 体験を提供します。 + +[ソーシャルサインイン体験](/end-user-flows/sign-up-and-sign-in/social-sign-in) について詳しく学ぶ。 + +### Google アカウントの連携・解除 \{#link-or-unlink-a-google-account} + +Account API を利用して、サインイン済みユーザーが Google アカウントを連携または解除できるカスタムアカウントセンターをアプリ内に構築できます。[Account API チュートリアルに従う](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Google コネクター (Connector) は、ソーシャルサインインを有効にせず、アカウント連携や API アクセスのみに利用することも可能です。 +::: + +### Google API へのアクセスとアクションの実行 \{#access-google-apis-and-perform-actions} + +アプリケーションは Secret Vault から保存された Google アクセストークン (Access token) を取得し、Google API を呼び出してバックエンドタスクを自動化できます（例：Google ドライブファイルの管理、カレンダーイベントの作成、Gmail でのメール送信など）。API アクセス用の保存トークン取得ガイドを参照してください。 + +## ユーザーの Google アイデンティティ管理 \{#manage-user-s-google-identity} + +ユーザーが Google アカウントを連携した後、管理者は Logto コンソールでその接続を管理できます： + +1. Logto コンソール > ユーザー管理 + に移動し、ユーザーのプロフィールを開きます。 +2. **ソーシャル接続** セクションで Google 項目を見つけ、**管理** をクリックします。 +3. このページで管理者はユーザーの Google 接続を管理し、Google アカウントから許可・同期されたすべてのプロフィール情報やアクセストークン (Access token) の状態を確認できます。 + +## 参考情報 \{#reference} - Google Identity: OAuth 2.0 の設定 + Google Identity: OAuth 2.0 のセットアップ + + + Google Identity Services (One Tap) + + +Google Cloud Console diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index ecae57176b5..6a6d16c15fb 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## Google API Console でプロジェクトを設定する \{#set-up-a-project-in-the-google-api-console} +## ステップ 1: Google Auth Platform でプロジェクトを作成する \{#step-1-create-a-project-on-google-auth-platform} + +Google を認証 (Authentication) プロバイダーとして利用する前に、Google Cloud Console でプロジェクトを作成し、OAuth 2.0 認証情報を取得する必要があります。すでにプロジェクトがある場合は、このステップをスキップできます。 + +1. [Google Cloud Console](https://console.cloud.google.com/) にアクセスし、Google アカウントでサインインします。 +2. 上部メニューバーの **プロジェクトを選択** ボタンをクリックし、**新しいプロジェクト** ボタンをクリックしてプロジェクトを作成します。 +3. 作成したプロジェクトで、**API とサービス > OAuth 同意画面** に移動し、アプリを設定します： + - **アプリ情報**：同意画面に表示される **アプリケーション名** と **サポートメール** を入力します + - **オーディエンス (Audience)**：希望するオーディエンスタイプを選択します： + - **内部** - 組織内の Google Workspace ユーザーのみ + - **外部** - すべての Google ユーザー向け（本番利用には検証が必要） + - **連絡先情報**：Google からプロジェクトの変更通知を受け取るためのメールアドレスを入力します + - **Google のポリシーに同意します** にチェックを入れて基本設定を完了します +4. 必要に応じて **ブランディング** セクションで製品情報を編集し、**アプリロゴ** をアップロードできます。OAuth 同意画面に表示され、ユーザーがアプリを認識しやすくなります。 + +:::tip +**外部** オーディエンスタイプを選択した場合、開発中はテストユーザーを追加し、本番利用時にはアプリを公開する必要があります。 +::: + +## ステップ 2: OAuth 2.0 認証情報を作成する \{#step-2-create-oauth-2-0-credentials} + +Google Cloud Console の [認証情報](https://console.cloud.google.com/apis/credentials) ページに移動し、アプリケーション用の OAuth 認証情報を作成します。 + +1. **認証情報を作成 > OAuth クライアント ID** をクリックします。 +2. アプリケーションの種類として **ウェブアプリケーション** を選択します。 +3. OAuth クライアントの **名前** を入力します。これは認証情報の識別用で、エンドユーザーには表示されません。 +4. 許可済み URI を設定します： + - **許可済み JavaScript オリジン**：Logto インスタンスのオリジン（例：`https://your-logto-domain.com`）を追加します + - **許可済みリダイレクト URI**：Logto の **Callback URI** を追加します（Logto Google コネクターからコピー） +5. **作成** をクリックして OAuth クライアントを生成します。 + +## ステップ 3: Logto コネクターに認証情報を設定する \{#step-3-configure-logto-connector-with-credentials} + +OAuth クライアント作成後、Google から認証情報が表示されます： + +1. **クライアント ID** をコピーし、Logto の `clientId` フィールドに貼り付けます +2. **クライアントシークレット** をコピーし、Logto の `clientSecret` フィールドに貼り付けます +3. Logto で **保存して完了** をクリックし、アイデンティティシステムと Google を接続します + +:::warning +クライアントシークレットは安全に保管し、クライアントサイドのコードで絶対に公開しないでください。漏洩した場合は直ちに新しいものを発行してください。 +::: + +## ステップ 4: スコープを設定する \{#step-4-configure-scopes} + +スコープ (Scope) は、アプリがユーザーから要求する権限を定義し、Google アカウントからどのデータにアクセスできるかを制御します。 + +### Google Cloud Console でスコープを設定する \{#configure-scopes-in-google-cloud-console} + +1. **API とサービス > OAuth 同意画面 > スコープ** に移動します。 +2. **スコープを追加または削除** をクリックし、アプリに必要なスコープのみを選択します： + - **認証 (Authentication)（必須）**： + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **API アクセス（任意）**：アプリに必要な追加スコープを追加します（例：Drive、Calendar、YouTube）。利用可能なサービスは [Google API ライブラリ](https://console.cloud.google.com/apis/library) で確認できます。基本権限以外の Google API へアクセスする場合は、まず Google API ライブラリで該当 API（例：Google Drive API、Gmail API、Calendar API）を有効化してください。 +3. **更新** をクリックして選択を確定します。 +4. **保存して続行** をクリックして変更を適用します。 -- [Google API Console](https://console.developers.google.com) にアクセスし、Google アカウントでサインインします。 -- 上部メニューバーの **プロジェクトを選択** ボタンをクリックし、**新しいプロジェクト** ボタンをクリックしてプロジェクトを作成します。 -- 新しく作成したプロジェクトで、**API とサービス** をクリックして **API とサービス** メニューに入ります。 +### Logto でスコープを設定する \{#configure-scopes-in-logto} -## 同意画面を設定する \{#configure-your-consent-screen} +ニーズに応じて、以下のいずれかの方法を選択してください： -### アプリケーションを設定して登録する \{#configure-and-register-your-application} +**オプション 1: 追加の API スコープが不要な場合** -- 左側の **API とサービス** メニューで、**OAuth 同意画面** ボタンをクリックします。 -- 希望する **ユーザータイプ** を選択し、**作成** ボタンをクリックします。（注：**ユーザータイプ** として **外部** を選択した場合、後でテストユーザーを追加する必要があります。） +- Logto Google コネクターの `Scopes` フィールドは空欄のままにします。 +- デフォルトで `openid profile email` スコープがリクエストされ、Logto が基本的なユーザー情報を正しく取得できます。 -これで **アプリ登録の編集** ページに移動します。 +**オプション 2: サインイン時に追加スコープをリクエストする場合** -### アプリ登録の編集 \{#edit-app-registration} +- 必要なすべてのスコープを **Scopes** フィールドにスペース区切りで入力します。 +- ここに記載したスコープがデフォルトを上書きするため、必ず認証 (Authentication) 用スコープ（`https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`）を含めてください。 +- スコープはフル URL で記載します。例：`https://www.googleapis.com/auth/calendar.readonly` -#### OAuth 同意画面の設定 \{#config-oauth-consent-screen} +**オプション 3: 後からインクリメンタルにスコープをリクエストする場合** -- 指示に従って **OAuth 同意画面** フォームに記入します。 -- **保存して続行** をクリックして続行します。 +- ユーザーがサインインした後、必要に応じてフェデレーテッドソーシャル認可 (Authorization) フローを再実行し、ユーザーのトークンセットを更新することで追加スコープをリクエストできます。 +- これらの追加スコープは Logto Google コネクターの `Scopes` フィールドに記載する必要はなく、Logto の Social Verification API を通じて実現できます。 -#### スコープの設定 \{#config-scopes} +これらの手順に従うことで、Logto Google コネクターはアプリに必要な権限だけをリクエストします。 -- **スコープを追加または削除** をクリックし、ポップアップドロワーで `../auth/userinfo.email`、`../auth/userinfo.profile`、`openid` を選択し、**更新** をクリックして完了します。使用する可能性のあるすべてのスコープを追加することをお勧めします。そうしないと、設定で追加した一部のスコープが機能しない場合があります。 -- 必要に応じてフォームに記入します。 -- **保存して続行** をクリックして続行します。 +:::tip +アプリがこれらのスコープをリクエストして Google API へアクセス・操作する場合は、Logto Google コネクターで **永続的な API アクセス用にトークンを保存** を有効にしてください。詳細は次のセクションを参照してください。 +::: -#### テストユーザーの追加（外部ユーザータイプのみ） \{#add-test-users-external-user-type-only} +## ステップ 5: 認証 (Authentication) プロンプトをカスタマイズする \{#step-5-customize-authentication-prompts} -- **ユーザーを追加** をクリックし、テストユーザーを追加して、これらのユーザーがテスト中にアプリケーションにアクセスできるようにします。 -- **保存して続行** をクリックして続行します。 +Logto で **Prompts** を設定し、ユーザー認証 (Authentication) 体験を制御できます。Prompts は、必要なユーザーインタラクションの種類を指定する文字列配列です： -これで Google OAuth 2.0 同意画面が設定されました。 +- `none` - 認可 (Authorization) サーバーは認証 (Authentication) や同意画面を表示しません。ユーザーがすでに認証 (Authentication) 済みかつ要求されたスコープに事前同意していない場合はエラーを返します。既存の認証 (Authentication) や同意の有無を確認する用途です。 +- `consent` - 認可 (Authorization) サーバーはクライアントに情報を返す前にユーザーに同意を求めます。Google API への **オフラインアクセス** を有効にするには必須です。 +- `select_account` - 認可 (Authorization) サーバーはユーザーにアカウント選択を促します。複数の Google アカウントを持つユーザーが認証 (Authentication) に使用するアカウントを選択できます。 -## OAuth 2.0 資格情報を取得する \{#obtain-oauth-20-credentials} +## ステップ 6: 一般設定 \{#step-6-general-settings} -- 左側の **API とサービス** メニューで、**資格情報** ボタンをクリックします。 -- **資格情報** ページで、上部メニューバーの **+ 資格情報を作成** ボタンをクリックし、**OAuth クライアント ID** を選択します。 -- **OAuth クライアント ID の作成** ページで、アプリケーションタイプとして **ウェブアプリケーション** を選択します。 -- アプリケーションの基本情報を入力します。 -- **+ URI を追加** をクリックして、**承認済みの JavaScript オリジン** セクションに承認済みドメインを追加します。これは、Logto 認可ページが提供されるドメインです。私たちの場合、これは `${your_logto_origin}` になります。例：`https://logto.dev`。 -- **承認済みリダイレクト URI** セクションで **+ URI を追加** をクリックして、**承認済みリダイレクト URI** を設定します。これは、ログイン後にユーザーをアプリケーションにリダイレクトするものです。私たちの場合、これは `${your_logto_endpoint}/callback/${connector_id}` になります。例：`https://logto.dev/callback/${connector_id}`。`connector_id` は Logto 管理コンソールのコネクター詳細ページの上部バーにあります。 -- **作成** をクリックして完了し、**クライアント ID** と **クライアントシークレット** を取得します。 +Google への接続自体には影響しませんが、エンドユーザーの認証 (Authentication) 体験に関わる一般的な設定です。 -## コネクターを設定する \{#configure-your-connector} +### プロフィール情報の同期 \{#sync-profile-information} -前のセクションで言及した OAuth アプリ詳細ページから取得した _クライアント ID_ と _クライアントシークレット_ を `clientId` と `clientSecret` フィールドに入力します。 +Google コネクターでは、ユーザー名やアバターなどのプロフィール情報の同期ポリシーを設定できます。選択肢は以下の通りです： -`scope` は、スペースで区切られた [スコープ](https://developers.google.com/identity/protocols/oauth2/scopes) のリストです。指定しない場合、スコープはデフォルトで `openid profile email` になります。 +- **サインアップ時のみ同期**：ユーザーが初回サインインしたときにプロフィール情報を取得します。 +- **サインイン時に常に同期**：ユーザーがサインインするたびにプロフィール情報を更新します。 -`prompts` は、必要なユーザーインタラクションのタイプを指定する文字列の配列です。文字列は次のいずれかの値になります： +### Google API へのトークン保存（任意） \{#store-tokens-to-access-google-apis-optional} -- `none`: 認可サーバーは認証またはユーザー同意画面を表示しません。ユーザーが既に認証されておらず、要求されたスコープに対する事前設定された同意がない場合、エラーを返します。既存の認証および / または同意を確認するために none を使用できます。 -- `consent`: 認可サーバーは、クライアントに情報を返す前にユーザーに同意を求めます。 -- `select_account`: 認可サーバーは、ユーザーにユーザーアカウントを選択するよう促します。これにより、認可サーバーに複数のアカウントを持つユーザーが、現在セッションを持つ複数のアカウントの中から選択できるようになります。 +[Google API](https://console.cloud.google.com/apis/library) へアクセスし、ユーザーの認可 (Authorization) のもとで操作を行いたい場合（ソーシャルサインインやアカウント連携経由）、Logto は特定の API スコープを取得し、トークンを保存する必要があります。 -### 設定タイプ \{#config-types} +1. 必要なスコープを Google Cloud Console の OAuth 同意画面設定と Logto Google コネクターに追加します。 +2. Logto Google コネクターで **永続的な API アクセス用にトークンを保存** を有効にします。Logto は Google のアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) を Secret Vault に安全に保存します。 +3. リフレッシュ トークン (Refresh token) を確実に取得するため、Logto Google コネクターの設定を以下のようにします： + - **Prompts** に `consent` を含める + - **オフラインアクセス** を有効にする -| 名前 | タイプ | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +Logto の `Scope` フィールドに `offline_access` を追加する必要はありません。追加するとエラーになる場合があります。Google ではオフラインアクセスが有効な場合、自動的に `access_type=offline` が使用されます。 +::: -## Google One Tap を有効にする \{#enable-google-one-tap} +## ステップ 7: Google One Tap を有効にする（任意） \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) は、ユーザーが Google アカウントでウェブサイトやアプリにサインインするための安全で簡単な方法です。 +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) は、ユーザーが Google アカウントでポップアップインターフェースを使ってウェブサイトにサインインできる安全かつシームレスな方法です。 -Google コネクターを設定すると、コネクター詳細ページに Google One Tap のカードが表示されます。スイッチを切り替えることで、サインアップおよびサインインページで Google One Tap を有効にできます。 +Google コネクターのセットアップが完了すると、コネクター詳細ページに Google One Tap 用のカードが表示されます。スイッチを切り替えて Google One Tap を有効にします。 -Google One Tap を有効にすると、次のオプションを設定できます： +### Google One Tap の設定オプション \{#google-one-tap-configuration-options} -- **可能であれば資格情報を自動選択**： [特定の条件が満たされた場合](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out)、Google アカウントで自動的にユーザーをサインインします。 -- **ユーザーが外側をクリック / タップした場合、プロンプトをキャンセル**：ユーザーがプロンプトの外側をクリックまたはタップした場合、Google One Tap プロンプトを閉じます。無効にすると、ユーザーはプロンプトを閉じるために閉じるボタンをクリックする必要があります。 -- **ITP ブラウザでのアップグレードされた One Tap UX を有効にする**：インテリジェントトラッキング防止 (ITP) ブラウザでアップグレードされた Google One Tap ユーザーエクスペリエンスを有効にします。詳細については [このページ](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) を参照してください。 +- **条件を満たせば自動で認証情報を選択** - [特定条件](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) を満たす場合、Google アカウントで自動的にサインインします +- **ユーザーが外側をクリック／タップしたらプロンプトをキャンセル** - ユーザーがプロンプト外をクリックまたはタップした場合、Google One Tap プロンプトを閉じます。無効の場合、ユーザーは閉じるボタンをクリックしてプロンプトを閉じる必要があります。 +- **ITP ブラウザでアップグレードされた One Tap UX を有効化** - Intelligent Tracking Prevention (ITP) ブラウザでアップグレードされた Google One Tap ユーザー体験を有効にします。詳細は [こちらのドキュメント](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) を参照してください。 -:::caution -サーバーのオリジンを OAuth 同意画面設定の **承認済みの JavaScript オリジン** セクションに追加してください。そうしないと、Google One Tap を表示できません。 +:::warning +OAuth クライアント設定の **許可済み JavaScript オリジン** セクションにドメインを追加してください。追加しないと Google One Tap は表示できません。 ::: +### Google One Tap の重要な制限事項 \{#important-limitations-with-google-one-tap} + +**永続的な API アクセス用にトークンを保存** と **Google One Tap** の両方を有効にしても、アクセス トークン (Access token) やリクエストしたスコープは自動的には取得できません。 + +Google One Tap サインイン（標準の「Google でサインイン」ボタンとは異なり）は、OAuth アクセス トークン (Access token) を発行しません。ID トークン (ID token)（署名付き JWT）だけが返され、ユーザーのアイデンティティは検証できますが、API アクセス権は付与されません。 + +Google One Tap ユーザーで Google API へアクセスするには、Logto の Social Verification API を使って、ユーザーが Google One Tap でサインインした後にフェデレーテッドソーシャル認可 (Authorization) フローを再実行してください。これにより、必要な追加スコープをリクエストし、ユーザーのトークンセットを更新できます。Logto Google コネクターのスコープ事前設定は不要です。この方法によりインクリメンタル認可 (Authorization) が可能となり、アプリが実際に必要とするタイミングでのみ追加権限の同意をユーザーに求められます。 + +[Google One Tap の制限事項](https://developers.google.com/identity/gsi/web/guides/overview) については公式ドキュメントもご参照ください。 + +## ステップ 8: アプリのテストと公開 \{#step-8-test-and-publish-your-app} + +### 内部アプリの場合 \{#for-internal-apps} + +Google の **オーディエンス (Audience)** タイプが **内部** の場合、アプリは組織内の Google Workspace ユーザーのみ利用可能です。組織の任意のアカウントでテストできます。 + +### 外部アプリの場合 \{#for-external-apps} + +**オーディエンス (Audience)** タイプが **外部** の場合： + +1. **開発中**：**OAuth 同意画面 > テストユーザー** に移動し、テストユーザーのメールアドレスを追加します。これらのユーザーのみがアプリでサインインできます。 +2. **本番利用時**：OAuth 同意画面セクションで **アプリを公開** をクリックし、すべての Google アカウントユーザーが利用できるようにします。 + :::note -ウェブサイトで Google One Tap を有効にするには（Logto サインイン体験を超えて）、この機能は開発中です。更新情報をお待ちください。 +センシティブまたは制限付きスコープを持つアプリは、公開前に Google の検証が必要な場合があります。このプロセスには数週間かかることがあります。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index a0c2904d910..7a08a5074f5 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -1,6 +1,6 @@ --- slug: /integrations/oauth2 -sidebar_label: OAuth 2.0 (Social) +sidebar_label: OAuth 2.0 (ソーシャル) sidebar_custom_props: description: OAuth 2.0 認可 (Authorization) フレームワークは、サードパーティアプリケーションが HTTP サービスへの限定的なアクセスを取得できるようにします。 logoFilename: 'oauth.svg' @@ -14,23 +14,36 @@ import Integration from './_integration.mdx'; # OAuth 2.0 プロトコルを使用してソーシャルログインを設定する -OAuth 2.0 プロトコル用の公式 Logto コネクター。 +OAuth 2.0 プロトコル用の公式 Logto コネクターです。 ## はじめに \{#get-started} -OAuth コネクターは、OAuth 2.0 プロトコルをサポートする任意のソーシャルアイデンティティプロバイダーへの Logto の接続を可能にします。 +OAuth コネクターは、OAuth 2.0 プロトコルをサポートする任意のソーシャルアイデンティティプロバイダー (IdP) への Logto の接続を可能にします。OAuth コネクターを利用することで、アプリケーションに以下の機能を追加できます： + +- ソーシャルサインインボタンの追加 +- ユーザーアカウントとソーシャルアイデンティティの連携 +- ソーシャルプロバイダーからユーザープロフィール情報の同期 +- Logto シークレットボールトでの安全なトークン保管を通じてサードパーティ API へアクセスし、自動化タスクを実行（例：Google ドキュメントの編集、アプリ内でのカレンダーイベント管理など） + +これらの認証 (Authentication) 機能を設定するには、まず Logto で OAuth 2.0 コネクターを作成してください： + +1. + Logto コンソール > コネクター > ソーシャルコネクター + + にアクセスします。 +2. **ソーシャルコネクターを追加** をクリックし、**OAuth 2.0** を選択、**次へ** をクリックし、ステップバイステップのチュートリアルに従って統合を完了してください。 :::note -OAuth コネクターは Logto の特別な種類のコネクターであり、いくつかの OAuth プロトコルベースのコネクターを追加できます。 +OAuth コネクターは Logto における特別な種類のコネクターであり、OAuth プロトコルベースのコネクターを複数追加できます。 ::: -## 参考文献 \{#reference} +## 参考資料 \{#reference} OAuth 2.0 認可 (Authorization) フレームワーク diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index 97c259eb878..31410519857 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ -## OAuth アプリを作成する \{#create-your-oauth-app} +## OAuth アプリの作成 \{#create-your-oauth-app} -このページを開いたときには、接続したいソーシャルアイデンティティプロバイダーがすでに決まっていると考えています。最初に行うべきことは、そのアイデンティティプロバイダーが OAuth プロトコルをサポートしていることを確認することです。これは有効なコネクターを設定するための前提条件です。その後、アイデンティティプロバイダーの指示に従って、OAuth 認可のための関連アプリを登録および作成します。 +このページを開いた時点で、接続したいソーシャルアイデンティティプロバイダーが決まっていると考えています。最初に行うべきことは、そのアイデンティティプロバイダーが OAuth プロトコルをサポートしているかを確認することです。これは有効なコネクターを構成するための前提条件です。その後、アイデンティティプロバイダーの指示に従って、OAuth 認可用の関連アプリを登録・作成してください。 -## コネクターを設定する \{#configure-your-connector} +## コネクターの構成 \{#configure-your-connector} -セキュリティ上の考慮から、"Authorization Code" グラントタイプのみをサポートしており、これは Logto のシナリオに完全に適合します。 +セキュリティ上の理由から「認可コード」グラントタイプのみをサポートしており、これは Logto のシナリオに完全に適合します。 -`clientId` と `clientSecret` は、OAuth アプリの詳細ページで見つけることができます。 +`clientId` と `clientSecret` は OAuth アプリの詳細ページで確認できます。 -_clientId_: クライアント ID は、認可サーバーへの登録時にクライアントアプリケーションを識別する一意の識別子です。この ID は、認可サーバーがクライアントアプリケーションのアイデンティティを確認し、その特定のクライアントアプリケーションに関連付けられた認可されたアクセス トークンを関連付けるために使用されます。 +_clientId_：クライアント ID は、認可サーバーへの登録時にクライアントアプリケーションを識別する一意の識別子です。この ID は、認可サーバーがクライアントアプリケーションのアイデンティティを確認し、発行されたアクセス トークンを特定のクライアントアプリケーションに関連付けるために使用されます。 -_clientSecret_: クライアントシークレットは、登録時に認可サーバーからクライアントアプリケーションに発行される秘密のキーです。クライアントアプリケーションは、この秘密キーを使用して、アクセス トークンを要求する際に認可サーバーに対して自分自身を認証します。クライアントシークレットは機密情報と見なされ、常に安全に保たれるべきです。 +_clientSecret_：クライアントシークレットは、登録時に認可サーバーからクライアントアプリケーションに発行される機密キーです。クライアントアプリケーションは、このシークレットキーを使用して、アクセス トークンをリクエストする際に認可サーバーに対して自身を認証します。クライアントシークレットは機密情報とみなされ、常に安全に保管する必要があります。 -_tokenEndpointAuthMethod_: トークンエンドポイント認証方法は、クライアントアプリケーションがアクセス トークンを要求する際に認可サーバーに対して自分自身を認証するために使用されます。サポートされている方法を確認するには、OAuth 2.0 サービスプロバイダーの OpenID Connect ディスカバリエンドポイントで利用可能な `token_endpoint_auth_methods_supported` フィールドを参照するか、OAuth 2.0 サービスプロバイダーが提供する関連ドキュメントを参照してください。 +_tokenEndpointAuthMethod_：トークンエンドポイント認証方式は、クライアントアプリケーションがアクセス トークンをリクエストする際に認可サーバーに対して自身を認証するために使用されます。サポートされている方式を確認するには、OAuth 2.0 サービスプロバイダーの OpenID Connect ディスカバリーエンドポイントで利用可能な `token_endpoint_auth_methods_supported` フィールドを参照するか、OAuth 2.0 サービスプロバイダーが提供する関連ドキュメントを参照してください。 -_clientSecretJwtSigningAlgorithm (オプション)_: `tokenEndpointAuthMethod` が `client_secret_jwt` の場合にのみ必要です。クライアントシークレット JWT 署名アルゴリズムは、トークンリクエスト中に認可サーバーに送信される JWT をクライアントアプリケーションが署名するために使用されます。 +_clientSecretJwtSigningAlgorithm (オプション)_：`tokenEndpointAuthMethod` が `client_secret_jwt` の場合のみ必要です。クライアントシークレット JWT 署名アルゴリズムは、トークンリクエスト時にクライアントアプリケーションが認可サーバーに送信する JWT に署名するために使用されます。 -_scope_: スコープパラメータは、クライアントアプリケーションがアクセスを要求しているリソースと権限のセットを指定するために使用されます。スコープパラメータは通常、特定の権限を表す値のスペースで区切られたリストとして定義されます。たとえば、スコープ値が "read write" の場合、クライアントアプリケーションがユーザーのデータへの読み取りおよび書き込みアクセスを要求していることを示すかもしれません。 +_scope_：スコープパラメーターは、クライアントアプリケーションがアクセスを要求するリソースと権限のセットを指定するために使用されます。スコープパラメーターは通常、特定の権限を表す値をスペース区切りで並べたリストとして定義されます。例えば、スコープ値が "read write" の場合、クライアントアプリケーションがユーザーデータの読み取りおよび書き込みアクセスを要求していることを示します。 -ソーシャルベンダーのドキュメントで `authorizationEndpoint`、`tokenEndpoint`、`userInfoEndpoint` を見つけることが期待されます。 +`authorizationEndpoint`、`tokenEndpoint`、`userInfoEndpoint` は、ソーシャルベンダーのドキュメントで確認できます。 -_authenticationEndpoint_: このエンドポイントは、認証 (Authentication) プロセスを開始するために使用されます。認証 (Authentication) プロセスには通常、ユーザーがログインし、クライアントアプリケーションがユーザーのリソースにアクセスするための認可を与えることが含まれます。 +_authenticationEndpoint_：このエンドポイントは認証 (Authentication) プロセスを開始するために使用されます。認証 (Authentication) プロセスは通常、ユーザーがログインし、クライアントアプリケーションにリソースへのアクセスを許可することを含みます。 -_tokenEndpoint_: このエンドポイントは、クライアントアプリケーションが要求されたリソースにアクセスするために使用できるアクセス トークンを取得するために使用されます。クライアントアプリケーションは通常、アクセス トークンを受け取るために、グラントタイプと認可コードを含むリクエストをトークンエンドポイントに送信します。 +_tokenEndpoint_：このエンドポイントは、クライアントアプリケーションがリクエストされたリソースにアクセスするために使用できるアクセス トークンを取得するために使用されます。クライアントアプリケーションは通常、グラントタイプと認可コードを含むリクエストをトークンエンドポイントに送信し、アクセス トークンを受け取ります。 -_userInfoEndpoint_: このエンドポイントは、クライアントアプリケーションがユーザーのフルネーム、メールアドレス、またはプロフィール写真などの追加情報を取得するために使用されます。ユーザー情報エンドポイントは通常、クライアントアプリケーションがトークンエンドポイントからアクセス トークンを取得した後にアクセスされます。 +_userInfoEndpoint_：このエンドポイントは、クライアントアプリケーションがユーザーのフルネーム、メールアドレス、プロフィール画像などの追加情報を取得するために使用されます。ユーザー情報エンドポイントは、クライアントアプリケーションがトークンエンドポイントからアクセス トークンを取得した後にアクセスされるのが一般的です。 -Logto は、通常標準ではないソーシャルベンダーのプロファイルからのマッピングをカスタマイズできる `profileMap` フィールドも提供しています。キーは Logto の標準ユーザープロファイルフィールド名であり、対応する値はソーシャルプロファイルのフィールド名であるべきです。現在の段階では、Logto はソーシャルプロファイルから 'id'、'name'、'avatar'、'email'、'phone' のみを考慮し、'id' のみが必須で、他はオプションフィールドです。 +Logto では、`profileMap` フィールドも提供しており、ソーシャルベンダーのプロフィール情報（通常は標準化されていない）からのマッピングをカスタマイズできます。キーは Logto の標準ユーザープロフィールフィールド名で、対応する値はソーシャルプロフィールのフィールド名です。現時点では、Logto はソーシャルプロフィールから 'id'、'name'、'avatar'、'email'、'phone' のみを対象とし、'id' のみ必須で他はオプションです。 -`responseType` と `grantType` は、認可コードグラントタイプでのみ固定値にできるため、オプションとし、デフォルト値が自動的に入力されます。 +`responseType` と `grantType` は認可コードグラントタイプでのみ固定値となるため、オプション扱いとし、デフォルト値が自動的に入力されます。 -たとえば、[Google ユーザープロファイルのレスポンス](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) を見つけることができ、そのため `profileMap` は次のようになります： +例えば、[Google ユーザープロフィールレスポンス](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) を参照でき、その `profileMap` は次のようになります： ```json { @@ -41,31 +41,98 @@ Logto は、通常標準ではないソーシャルベンダーのプロファ :::note -カスタマイズパラメータを配置するためのオプションの `customConfig` キーを提供しています。 -各ソーシャルアイデンティティプロバイダーは、OAuth 標準プロトコルに独自のバリエーションを持つことがあります。希望するソーシャルアイデンティティプロバイダーが OAuth 標準プロトコルに厳密に従っている場合、`customConfig` を気にする必要はありません。 +カスタマイズパラメーターを格納するためのオプションの `customConfig` キーを用意しています。 +各ソーシャルアイデンティティプロバイダーは、OAuth 標準プロトコルに独自のバリエーションを持つ場合があります。ご利用のソーシャルアイデンティティプロバイダーが OAuth 標準プロトコルに厳密に準拠している場合は、`customConfig` を気にする必要はありません。 ::: ## 設定タイプ \{#config-types} -| 名前 | タイプ | 必須 | -| ------------------------- | ----------------------- | ----- | -| authorizationEndpoint | string | true | -| userInfoEndpoint | string | true | -| clientId | string | true | -| clientSecret | string | true | -| tokenEndpointResponseType | enum | false | -| responseType | string | false | -| grantType | string | false | -| tokenEndpoint | string | false | -| scope | string | false | -| customConfig | Record\ | false | -| profileMap | ProfileMap | false | - -| ProfileMap フィールド | タイプ | 必須 | デフォルト値 | -| --------------------- | ------ | ----- | ------------ | -| id | string | false | id | -| name | string | false | name | -| avatar | string | false | avatar | -| email | string | false | email | -| phone | string | false | phone | +| Name | Type | Required | +| ------------------------- | ----------------------- | -------- | +| authorizationEndpoint | string | true | +| userInfoEndpoint | string | true | +| clientId | string | true | +| clientSecret | string | true | +| tokenEndpointResponseType | enum | false | +| responseType | string | false | +| grantType | string | false | +| tokenEndpoint | string | false | +| scope | string | false | +| customConfig | Record\ | false | +| profileMap | ProfileMap | false | + +| ProfileMap fields | Type | Required | Default value | +| ----------------- | ------ | -------- | ------------- | +| id | string | false | id | +| name | string | false | name | +| avatar | string | false | avatar | +| email | string | false | email | +| phone | string | false | phone | + +## 一般設定 \{#general-settings} + +ここでは、アイデンティティプロバイダーへの接続を妨げることはありませんが、エンドユーザーの認証 (Authentication) 体験に影響を与える可能性のある一般的な設定を紹介します。 + +### ソーシャルボタン名とロゴ \{#social-button-name-and-logo} + +ログインページにソーシャルボタンを表示したい場合は、ソーシャルアイデンティティプロバイダーの **名前** と **ロゴ**（ダークモード・ライトモード）を設定できます。これにより、ユーザーがソーシャルログインオプションを認識しやすくなります。 + +### アイデンティティプロバイダー名 \{#identity-provider-name} + +各ソーシャルコネクターには、ユーザーアイデンティティを区別するための一意のアイデンティティプロバイダー (IdP) 名があります。一般的なコネクターは固定の IdP 名を使用しますが、カスタムコネクターは一意の値が必要です。詳細は [IdP 名について](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) をご覧ください。 + +### プロフィール情報の同期 \{#sync-profile-information} + +OAuth コネクターでは、ユーザー名やアバターなどのプロフィール情報の同期ポリシーを設定できます。以下から選択可能です： + +- **サインアップ時のみ同期**：ユーザーが初めてサインインしたときにプロフィール情報を一度だけ取得します。 +- **サインイン時に常に同期**：ユーザーがサインインするたびにプロフィール情報を更新します。 + +### サードパーティ API へのトークン保存（オプション） \{#store-tokens-to-access-third-party-apis-optional} + +アイデンティティプロバイダーの API にアクセスし、ユーザーの認可で操作を行いたい場合（ソーシャルサインインまたはアカウント連携経由）、Logto は特定の API スコープを取得し、トークンを保存する必要があります。 + +1. 上記の手順に従い、**scope** フィールドに必要なスコープを追加します +2. Logto OAuth コネクターで **API への永続的なアクセスのためにトークンを保存** を有効にします。Logto はアクセス トークンを Secret Vault に安全に保存します。 +3. **標準** の OAuth/OIDC アイデンティティプロバイダーの場合、リフレッシュ トークンを取得するには `offline_access` スコープを含める必要があり、これによりユーザーの同意プロンプトの繰り返しを防ぎます。 + +:::warning +クライアントシークレットは安全に保管し、クライアントサイドのコードで絶対に公開しないでください。漏洩した場合は、アイデンティティプロバイダーのアプリ設定で直ちに新しいものを発行してください。 +::: + +## OAuth コネクターの活用 \{#utilize-the-oauth-connector} + +OAuth コネクターを作成し、アイデンティティプロバイダーと接続したら、エンドユーザーフローに組み込むことができます。ニーズに合ったオプションを選択してください： + +### ソーシャルサインインボタンの有効化 \{#enable-social-sign-in-button} + +1. Logto コンソールで サインイン体験 > サインアップとサインイン に移動します。 +2. **ソーシャルサインイン** セクションで OAuth コネクターを追加し、ユーザーがアイデンティティプロバイダーで認証 (Authentication) できるようにします。 + +[ソーシャルサインイン体験](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in) について詳しく学ぶ。 + +### ソーシャルアカウントの連携・解除 \{#link-or-unlink-a-social-account} + +Account API を利用して、アプリ内でサインイン済みユーザーがソーシャルアカウントを連携・解除できるカスタムアカウントセンターを構築できます。[Account API チュートリアルを参照](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +OAuth コネクターは、ソーシャルサインインを有効にせず、アカウント連携や API アクセスのみに利用することも可能です。 +::: + +### アイデンティティプロバイダー API へのアクセスと操作 \{#access-identity-provider-apis-and-perform-actions} + +アプリケーションは Secret Vault から保存されたアクセス トークンを取得し、アイデンティティプロバイダーの API を呼び出してバックエンドタスクを自動化できます。具体的な機能は、アイデンティティプロバイダーとリクエストしたスコープによって異なります。API アクセス用の保存トークン取得ガイドを参照してください。 + +## ユーザーのソーシャルアイデンティティ管理 \{#manage-user-s-social-identity} + +ユーザーがソーシャルアカウントを連携した後、管理者は Logto コンソールでその接続を管理できます： + +1. Logto コンソール > ユーザー管理 + に移動し、ユーザープロフィールを開きます。 +2. **ソーシャル接続** セクションでアイデンティティプロバイダー項目を見つけ、**管理** をクリックします。 +3. このページで管理者は、ユーザーのソーシャル接続を管理し、ソーシャルアカウントから付与・同期されたすべてのプロフィール情報を確認し、アクセス トークンの状態をチェックできます。 + +:::note +一部のアイデンティティプロバイダーのアクセス トークンレスポンスには、特定のスコープ情報が含まれていない場合があります。そのため、Logto ではユーザーが付与した権限リストを直接表示できません。ただし、ユーザーが認可時にリクエストされたスコープに同意していれば、アプリケーションは OAuth API へアクセスする際に対応する権限を持ちます。 +::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index be244c0a808..53ff77ef3d7 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -1,8 +1,8 @@ --- slug: /integrations/oidc -sidebar_label: OIDC (Social) +sidebar_label: OIDC (ソーシャル) sidebar_custom_props: - description: OpenID Connect 1.0 は、OAuth 2.0 プロトコルの上に構築されたシンプルなアイデンティティレイヤーです。 + description: OpenID Connect 1.0 は OAuth 2.0 プロトコル上に構築されたシンプルなアイデンティティレイヤーです。 tutorial_name: OIDC tutorial_config_name: Standard OIDC app --- @@ -13,17 +13,30 @@ import Integration from './_integration.mdx'; # OpenID Connect (OIDC) を使用してソーシャルログインを設定する -OpenID Connect (OIDC) プロトコル用の公式 Logto コネクター。 +OpenID Connect (OIDC) プロトコル用の公式 Logto コネクターです。 ## はじめに \{#get-started} -OIDC コネクターは、OIDC プロトコルをサポートする任意のソーシャルアイデンティティプロバイダーへの Logto の接続を可能にします。 +OIDC コネクターは、OIDC プロトコルをサポートする任意のソーシャルアイデンティティプロバイダー (IdP) への Logto の接続を可能にします。OIDC コネクターを利用することで、アプリケーションに以下の機能を追加できます： + +- ソーシャルサインインボタンの追加 +- ユーザーアカウントとソーシャルアイデンティティの連携 +- ソーシャルプロバイダーからのユーザープロフィール情報の同期 +- Logto Secret Vault での安全なトークン保存を通じたサードパーティ API へのアクセス（例：Google ドキュメントの編集やアプリ内でのカレンダーイベント管理などの自動化タスク） + +これらの認証 (Authentication) 機能を設定するには、まず Logto で OIDC コネクターを作成してください： + +1. + Logto コンソール > コネクター > ソーシャルコネクター + + にアクセスします。 +2. **ソーシャルコネクターを追加** をクリックし、**OIDC** を選択、**次へ** をクリックし、手順に従って統合を完了してください。 :::note -OIDC コネクターは Logto の特別な種類のコネクターであり、いくつかの OIDC ベースのコネクターを追加できます。 +OIDC コネクターは Logto で特別な種類のコネクターであり、複数の OIDC プロトコルベースのコネクターを追加できます。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index 18340590de9..b578588f230 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,51 +1,51 @@ -## OIDC アプリを作成する \{#create-your-oidc-app} +## OIDC アプリの作成 \{#create-your-oidc-app} -このページを開いたときには、接続したいソーシャルアイデンティティプロバイダーがすでにわかっていると考えています。最初に行うべきことは、アイデンティティプロバイダーが OIDC プロトコルをサポートしていることを確認することです。これは有効なコネクターを設定するための前提条件です。その後、アイデンティティプロバイダーの指示に従って、OIDC 認可のための関連アプリを登録して作成します。 +このページを開いた時点で、接続したいソーシャルアイデンティティプロバイダーが決まっていることを前提としています。最初に行うべきことは、そのアイデンティティプロバイダーが OIDC プロトコルをサポートしているかを確認することです。これは有効なコネクターを構成するための前提条件です。その後、アイデンティティプロバイダーの手順に従って、OIDC 認可用の関連アプリを登録・作成してください。 -## コネクターを設定する \{#configure-your-connector} +## コネクターの構成 \{#configure-your-connector} -セキュリティ上の考慮から、「Authorization Code」グラントタイプのみをサポートしており、これは Logto のシナリオに完全に適合します。 +セキュリティ上の理由から「認可コード (Authorization Code)」グラントタイプのみをサポートしており、これは Logto のシナリオに完全に適合します。 -`clientId` と `clientSecret` は、OIDC アプリの詳細ページで見つけることができます。 +`clientId` と `clientSecret` は OIDC アプリの詳細ページで確認できます。 -_clientId_: クライアント ID は、認可サーバーへの登録時にクライアントアプリケーションを識別する一意の識別子です。この ID は、認可サーバーがクライアントアプリケーションのアイデンティティを確認し、その特定のクライアントアプリケーションに関連付けられた認可されたアクセス トークンを関連付けるために使用されます。 +_clientId_：クライアント ID は、認可サーバーへの登録時にクライアントアプリケーションを識別する一意の識別子です。この ID は、認可サーバーがクライアントアプリケーションのアイデンティティを確認し、発行されたアクセス トークンを特定のクライアントアプリケーションに関連付けるために使用されます。 -_clientSecret_: クライアントシークレットは、登録時に認可サーバーからクライアントアプリケーションに発行される秘密のキーです。クライアントアプリケーションは、この秘密キーを使用して、アクセス トークンを要求する際に認可サーバーに対して自分自身を認証します。クライアントシークレットは機密情報と見なされ、常に安全に保たれるべきです。 +_clientSecret_：クライアントシークレットは、登録時に認可サーバーからクライアントアプリケーションに発行される秘密鍵です。クライアントアプリケーションは、この秘密鍵を使用して、アクセス トークンを要求する際に認可サーバーに対して自身を認証します。クライアントシークレットは機密情報と見なされ、常に安全に保管する必要があります。 -_tokenEndpointAuthMethod_: トークンエンドポイント認証方法は、クライアントアプリケーションがアクセス トークンを要求する際に認可サーバーに対して自分自身を認証するために使用されます。サポートされている方法を確認するには、OAuth 2.0 サービスプロバイダーの OpenID Connect ディスカバリーエンドポイントで利用可能な `token_endpoint_auth_methods_supported` フィールドを参照するか、OAuth 2.0 サービスプロバイダーが提供する関連ドキュメントを参照してください。 +_tokenEndpointAuthMethod_：トークンエンドポイント認証方式は、クライアントアプリケーションがアクセス トークンを要求する際に認可サーバーに対して自身を認証するために使用されます。サポートされている方式を確認するには、OAuth 2.0 サービスプロバイダーの OpenID Connect ディスカバリエンドポイントで利用可能な `token_endpoint_auth_methods_supported` フィールドを参照するか、OAuth 2.0 サービスプロバイダーが提供する関連ドキュメントを参照してください。 -_clientSecretJwtSigningAlgorithm (オプション)_: `tokenEndpointAuthMethod` が `client_secret_jwt` の場合にのみ必要です。クライアントシークレット JWT 署名アルゴリズムは、トークンリクエスト中に認可サーバーに送信される JWT をクライアントアプリケーションが署名するために使用されます。 +_clientSecretJwtSigningAlgorithm (オプション)_：`tokenEndpointAuthMethod` が `client_secret_jwt` の場合のみ必要です。クライアントシークレット JWT 署名アルゴリズムは、トークンリクエスト時にクライアントアプリケーションが認可サーバーに送信する JWT に署名するために使用されます。 -_scope_: スコープパラメーターは、クライアントアプリケーションがアクセスを要求しているリソースと権限のセットを指定するために使用されます。スコープパラメーターは通常、特定の権限を表す値のスペース区切りリストとして定義されます。たとえば、スコープ値が「read write」の場合、クライアントアプリケーションがユーザーのデータへの読み取りおよび書き込みアクセスを要求していることを示すかもしれません。 +_scope_：スコープパラメーターは、クライアントアプリケーションがアクセスを要求するリソースと権限のセットを指定するために使用されます。スコープパラメーターは通常、特定の権限を表す値をスペース区切りで並べたリストとして定義されます。例えば、スコープ値が "read write" の場合、クライアントアプリケーションがユーザーデータの読み取りおよび書き込みアクセスを要求していることを示します。 -`authorizationEndpoint`、`tokenEndpoint`、`jwksUri`、および `issuer` を OpenID プロバイダーの構成情報として見つけることが期待されます。これらはソーシャルベンダーのドキュメントで利用可能であるべきです。 +`authorizationEndpoint`、`tokenEndpoint`、`jwksUri`、`issuer` は、OpenID プロバイダーの構成情報として見つけることが期待されます。これらはソーシャルベンダーのドキュメントで確認できるはずです。 -_authenticationEndpoint_: このエンドポイントは、認証プロセスを開始するために使用されます。認証プロセスは通常、ユーザーがログインし、クライアントアプリケーションがリソースにアクセスするための認可を与えることを含みます。 +_authenticationEndpoint_：このエンドポイントは認証 (Authentication) プロセスを開始するために使用されます。認証 (Authentication) プロセスは通常、ユーザーがログインし、クライアントアプリケーションがリソースへのアクセスを許可することを含みます。 -_tokenEndpoint_: このエンドポイントは、クライアントアプリケーションが要求されたリソースにアクセスするために使用できる ID トークンを取得するために使用されます。クライアントアプリケーションは通常、トークンエンドポイントにグラントタイプと認可コードを含むリクエストを送信して、ID トークンを受け取ります。 +_tokenEndpoint_：このエンドポイントは、クライアントアプリケーションが要求されたリソースにアクセスするために使用できる ID トークンを取得するために使用されます。クライアントアプリケーションは通常、トークンエンドポイントにグラントタイプと認可コードを含むリクエストを送信し、ID トークンを受け取ります。 -_jwksUri_: これは、ソーシャルアイデンティティプロバイダー（略して IdP）の JSON Web Key Set (JWKS) を取得できる URL エンドポイントです。JWKS は、認証プロセス中に発行される JSON Web トークン (JWT) を IdP が署名および検証するために使用する暗号化キーのセットです。`jwksUri` は、IdP が JWT に署名するために使用する公開鍵を取得するために RP が使用し、RP が IdP から受け取った JWT の真正性と整合性を検証できるようにします。 +_jwksUri_：これは、ソーシャルアイデンティティプロバイダー（略して IdP）の JSON Web Key Set (JWKS) を取得できる URL エンドポイントです。JWKS は、IdP が認証 (Authentication) プロセス中に発行する JSON Web Token (JWT) に署名および検証するために使用する暗号鍵のセットです。`jwksUri` は、リライングパーティ (RP) が IdP によって署名された JWT の公開鍵を取得するために使用され、RP は IdP から受け取った JWT の真正性と完全性を検証できます。 -_issuer_: これは、IdP から受け取った JWT を RP が検証するために使用する IdP の一意の識別子です。これは JWT に `iss` [クレーム](https://www.rfc-editor.org/rfc/rfc7519#section-4) として含まれています（ID トークンは常に JWT です）。発行者の値は、IdP の認可サーバーの URL と一致する必要があり、RP が信頼する URI である必要があります。RP が JWT を受け取ると、`iss` クレームを確認して、それが信頼できる IdP によって発行されたものであり、RP で使用することを意図していることを確認します。 +_issuer_：これは、RP が IdP から受け取った JWT を検証するために使用する IdP の一意の識別子です。JWT には `iss` [クレーム](https://www.rfc-editor.org/rfc/rfc7519#section-4) として含まれています（ID トークンは常に JWT です）。issuer の値は、IdP の認可サーバーの URL と一致する必要があり、RP が信頼する URI である必要があります。RP が JWT を受け取ると、`iss` クレームを確認して、それが信頼できる IdP によって発行されたものであり、RP で使用することを意図していることを確認します。 -`jwksUri` と `issuer` は、認証プロセス中に RP がエンドユーザーのアイデンティティを検証するための安全なメカニズムを提供します。`jwksUri` から取得した公開鍵を使用することで、RP は IdP によって発行された JWT の真正性と整合性を検証できます。発行者の値は、RP が信頼できる IdP によって発行された JWT のみを受け入れ、JWT が RP で使用することを意図していることを保証します。 +`jwksUri` と `issuer` を組み合わせることで、RP は認証 (Authentication) プロセス中にエンドユーザーのアイデンティティを安全に検証できます。`jwksUri` から取得した公開鍵を使用して、RP は IdP が発行した JWT の真正性と完全性を検証できます。issuer の値により、RP は信頼できる IdP によって発行された JWT のみを受け入れ、JWT が RP で使用されることを保証します。 -認証リクエストは常に必要であるため、`authRequestOptionalConfig` が提供され、すべてのオプション設定をラップします。詳細は [OIDC 認証リクエスト](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) を参照してください。また、この設定に `nonce` が欠けていることに気付くかもしれません。`nonce` は各リクエストで同一である必要があるため、`nonce` の生成はコード実装に含めています。心配しないでください！前述の `jwksUri` と `issuer` も `idTokenVerificationConfig` に含まれています。 +認証リクエストは常に必要なため、`authRequestOptionalConfig` でオプション設定をまとめて指定できます。詳細は [OIDC 認証リクエスト](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) を参照してください。また、この設定に `nonce` が含まれていないことに気付くかもしれません。`nonce` は各リクエストごとに一意である必要があるため、nonce の生成はコード実装側に任せています。ご安心ください。前述の `jwksUri` と `issuer` も `idTokenVerificationConfig` に含まれています。 -標準の OIDC プロトコルがインプリシットおよびハイブリッドフローの両方をサポートしているのに対し、Logto コネクターが認可フローのみをサポートしている理由に興味があるかもしれません。インプリシットおよびハイブリッドフローは、認可フローよりも安全性が低いと判断されています。Logto はセキュリティに重点を置いているため、ユーザーに最高レベルのセキュリティを提供するために、認可フローのみをサポートしていますが、若干の不便さがあります。 +標準の OIDC プロトコルがインプリシットフローやハイブリッドフローもサポートしているのに、Logto コネクターが認可フローのみをサポートしている理由が気になるかもしれません。インプリシットフローやハイブリッドフローは認可フローよりもセキュリティが低いことが判明しています。Logto はセキュリティを重視しているため、多少利便性が劣るものの、ユーザーに最高レベルのセキュリティを提供するために認可フローのみをサポートしています。 -`responseType` と `grantType` は「Authorization Code」フローでのみ固定値にできるため、オプションとして設定し、デフォルト値が自動的に入力されます。 +`responseType` と `grantType` は「認可コード (Authorization Code)」フローでのみ固定値となるため、オプション扱いとし、デフォルト値が自動的に設定されます。 :::note -すべてのフロータイプに対して、カスタマイズパラメーターを配置するためのオプションの `customConfig` キーを提供しています。 -各ソーシャルアイデンティティプロバイダーは、OIDC 標準プロトコルに独自のバリアントを持つことがあります。希望するソーシャルアイデンティティプロバイダーが OIDC 標準プロトコルに厳密に従っている場合、`customConfig` を気にする必要はありません。 +すべてのフロータイプに対して、カスタマイズパラメーターを格納するためのオプションの `customConfig` キーを用意しています。 +各ソーシャルアイデンティティプロバイダーは OIDC 標準プロトコルに独自のバリエーションを持つ場合があります。ご希望のソーシャルアイデンティティプロバイダーが OIDC 標準プロトコルに厳密に準拠している場合、`customConfig` を気にする必要はありません。 ::: ## 設定タイプ \{#config-types} -| 名前 | タイプ | 必須 | +| 名前 | 型 | 必須 | | ------------------------- | ------------------------- | ----- | | scope | string | True | | clientId | string | True | @@ -56,30 +56,97 @@ _issuer_: これは、IdP から受け取った JWT を RP が検証するため | authRequestOptionalConfig | AuthRequestOptionalConfig | False | | customConfig | Record\ | False | -| AuthRequestOptionalConfig プロパティ | タイプ | 必須 | -| ------------------------------------ | ------ | ----- | -| responseType | string | False | -| tokenEndpoint | string | False | -| responseMode | string | False | -| display | string | False | -| prompt | string | False | -| maxAge | string | False | -| uiLocales | string | False | -| idTokenHint | string | False | -| loginHint | string | False | -| acrValues | string | False | - -| IdTokenVerificationConfig プロパティ | タイプ | 必須 | -| ------------------------------------ | ---------------------------------- | ----- | -| jwksUri | string | True | -| issuer | string \| string[] | False | -| audience | string \| string[] | False | -| algorithms | string[] | False | -| clockTolerance | string \| number | False | -| crit | Record\ | False | -| currentDate | Date | False | -| maxTokenAge | string \| number | False | -| subject | string | False | -| typ | string | False | +| AuthRequestOptionalConfig のプロパティ | 型 | 必須 | +| -------------------------------------- | ------ | ----- | +| responseType | string | False | +| tokenEndpoint | string | False | +| responseMode | string | False | +| display | string | False | +| prompt | string | False | +| maxAge | string | False | +| uiLocales | string | False | +| idTokenHint | string | False | +| loginHint | string | False | +| acrValues | string | False | + +| IdTokenVerificationConfig のプロパティ | 型 | 必須 | +| -------------------------------------- | ---------------------------------- | ----- | +| jwksUri | string | True | +| issuer | string \| string[] | False | +| audience | string \| string[] | False | +| algorithms | string[] | False | +| clockTolerance | string \| number | False | +| crit | Record\ | False | +| currentDate | Date | False | +| maxTokenAge | string \| number | False | +| subject | string | False | +| typ | string | False | `IdTokenVerificationConfig` の詳細については [こちら](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) を参照してください。 + +## 一般設定 \{#general-settings} + +ここでは、アイデンティティプロバイダーへの接続を妨げることはありませんが、エンドユーザーの認証 (Authentication) 体験に影響を与える可能性のある一般的な設定を紹介します。 + +### ソーシャルボタンの名前とロゴ \{#social-button-name-and-logo} + +ログインページにソーシャルボタンを表示したい場合は、ソーシャルアイデンティティプロバイダーの **名前** と **ロゴ**（ダークモード・ライトモード）を設定できます。これにより、ユーザーがソーシャルログインオプションを認識しやすくなります。 + +### アイデンティティプロバイダー名 \{#identity-provider-name} + +各ソーシャルコネクターには、ユーザーアイデンティティを区別するための一意のアイデンティティプロバイダー (IdP) 名があります。一般的なコネクターは固定の IdP 名を使用しますが、カスタムコネクターは一意の値が必要です。詳細は [IdP 名について](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) をご覧ください。 + +### プロフィール情報の同期 \{#sync-profile-information} + +OIDC コネクターでは、ユーザー名やアバターなどのプロフィール情報の同期ポリシーを設定できます。以下から選択可能です： + +- **サインアップ時のみ同期**：ユーザーが初めてサインインしたときにプロフィール情報を一度だけ取得します。 +- **サインイン時に常に同期**：ユーザーがサインインするたびにプロフィール情報を更新します。 + +### サードパーティ API へのトークン保存（オプション） \{#store-tokens-to-access-third-party-apis-optional} + +アイデンティティプロバイダーの API にアクセスし、ユーザーの認可のもとで操作（ソーシャルサインインやアカウント連携経由）を行いたい場合、Logto は特定の API スコープを取得し、トークンを保存する必要があります。 + +1. 上記の手順に従い、**scope** フィールドに必要なスコープを追加します +2. Logto OIDC コネクターで **API への永続的なトークン保存** を有効にします。Logto はアクセス トークンを Secret Vault に安全に保存します。 +3. **標準** の OAuth/OIDC アイデンティティプロバイダーの場合、リフレッシュ トークンを取得するには `offline_access` スコープを含める必要があり、ユーザーへの同意プロンプトの繰り返しを防ぎます。 + +:::warning +クライアントシークレットは安全に保管し、クライアントサイドのコードで絶対に公開しないでください。漏洩した場合は、アイデンティティプロバイダーのアプリ設定で直ちに新しいものを発行してください。 +::: + +## OIDC コネクターの活用 \{#utilize-the-oidc-connector} + +OIDC コネクターを作成し、アイデンティティプロバイダーと接続したら、エンドユーザーフローに組み込むことができます。ニーズに合ったオプションを選択してください： + +### ソーシャルサインインボタンの有効化 \{#enable-social-sign-in-button} + +1. Logto コンソールで サインイン体験 > サインアップとサインイン に移動します。 +2. **ソーシャルサインイン** セクションで OIDC コネクターを追加し、ユーザーがアイデンティティプロバイダーで認証 (Authentication) できるようにします。 + +[ソーシャルサインイン体験](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in) について詳しく学ぶことができます。 + +### ソーシャルアカウントの連携・解除 \{#link-or-unlink-a-social-account} + +Account API を利用して、アプリ内でサインイン済みユーザーがソーシャルアカウントを連携・解除できるカスタムアカウントセンターを構築できます。[Account API チュートリアルに従う](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +ソーシャルサインインを有効にせず、アカウント連携や API アクセスのためだけに OIDC コネクターを有効にすることも可能です。 +::: + +### アイデンティティプロバイダー API へのアクセスと操作 \{#access-identity-provider-apis-and-perform-actions} + +アプリケーションは Secret Vault から保存されたアクセス トークンを取得し、アイデンティティプロバイダーの API を呼び出してバックエンドタスクを自動化できます。具体的な機能は、アイデンティティプロバイダーと要求したスコープによって異なります。API アクセス用の保存トークン取得ガイドを参照してください。 + +## ユーザーのソーシャルアイデンティティ管理 \{#manage-user-s-social-identity} + +ユーザーがソーシャルアカウントを連携した後、管理者は Logto コンソールでその接続を管理できます： + +1. Logto コンソール > ユーザー管理 + に移動し、ユーザーのプロフィールを開きます。 +2. **ソーシャル接続** セクションでアイデンティティプロバイダー項目を見つけ、**管理** をクリックします。 +3. このページで管理者はユーザーのソーシャル接続を管理し、ソーシャルアカウントから付与・同期されたすべてのプロフィール情報やアクセス トークンの状態を確認できます。 + +:::note +一部のアイデンティティプロバイダーのアクセス トークンレスポンスには、特定のスコープ情報が含まれていない場合があります。そのため、Logto ではユーザーが付与した権限リストを直接表示できません。ただし、ユーザーが認可時に要求されたスコープに同意していれば、アプリケーションは OIDC API にアクセスする際に対応する権限を持ちます。 +::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index 6f1e1e3f84e..16e12cfda20 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: Google エコシステム内でのユーザーアクセスの統一された安全な管理。 + description: Google エコシステム内でのユーザーアクセスの統合的かつ安全な管理。 logoFilename: 'google.svg' tutorial_name: Google Workspace enterprise SSO tutorial_config_name: Google Cloud Platform @@ -16,10 +16,11 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; # Google Workspace を使用してシングルサインオンを設定する -最小限の設定作業で、このコネクターを使用して Microsoft Entra ID と統合し、エンタープライズシングルサインオン (SSO) を実現できます。 +最小限の設定で、このコネクターを利用して Microsoft Entra ID とのエンタープライズシングルサインオン (SSO) 連携が可能です。 @@ -31,18 +32,22 @@ import Step6 from './_step-6.mdx'; -## ステップ 3: 新しい OAuth 資格情報を作成する \{#step-3-create-a-new-oauth-credential} +## ステップ 3: 新しい OAuth クレデンシャルを作成する \{#step-3-create-a-new-oauth-credential} -## ステップ 4: クライアント資格情報を使用して Logto コネクターを設定する \{#step-4-set-up-logto-connector-with-the-client-credentials} +## ステップ 4: クライアントクレデンシャルで Logto コネクターを設定する \{#step-4-set-up-logto-connector-with-the-client-credentials} -## ステップ 5: 追加のスコープ (オプション) \{#step-5-additional-scopes-optional} +## ステップ 5: 追加スコープ（オプション） \{#step-5-additional-scopes-optional} -## ステップ 6: メールドメインを設定し、SSO コネクターを有効にする \{#step-6-set-email-domains-and-enable-the-sso-connector} +## ステップ 6: Google API へアクセスするためのトークンを保存する（オプション） \{#step-6-store-tokens-to-access-google-apis-optional} + +## ステップ 7: メールドメインを設定し、SSO コネクターを有効化する \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index 8613ef5c268..724a4350e61 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,12 +4,13 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; ### ステップ 1: Google Cloud Platform で新しいプロジェクトを作成する \{#step-1-create-a-new-project-on-google-cloud-platform} -### ステップ 2: アプリケーションの同意画面を設定する \{#step-2-config-the-consent-screen-for-your-application} +### ステップ 2: アプリケーションの同意画面 (Consent screen) を設定する \{#step-2-config-the-consent-screen-for-your-application} @@ -21,10 +22,14 @@ import Step6 from './_step-6.mdx'; -### ステップ 5: 追加のスコープ (オプション) \{#step-5-additional-scopes-optional} +### ステップ 5: 追加のスコープ (Scopes)（オプション） \{#step-5-additional-scopes-optional} -### ステップ 6: メールドメインを設定し、SSO コネクターを有効にする \{#step-6-set-email-domains-and-enable-the-sso-connector} +### ステップ 6: Google API へアクセスするためのトークンを保存する（オプション） \{#step-6-store-tokens-to-access-google-apis-optional} + +### ステップ 7: メールドメインを設定し、SSO コネクターを有効化する \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index a7cd44a2618..5ace575a4fc 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -`Scope` フィールドを使用して、OAuth リクエストに追加のスコープを追加します。これにより、Google OAuth サーバーからより多くの情報を要求できます。詳細については、 [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) ドキュメントを参照してください。 +スコープ (Scopes) は、アプリがユーザーから要求する権限 (Permissions) を定義し、Google Workspace アカウントからアプリがアクセスできるデータを制御します。Google の権限 (Permissions) をリクエストするには、両方の側で設定が必要です： -カスタムスコープ設定に関係なく、Logto は常に `openid`、`profile`、および `email` スコープを IdP に送信します。これは、Logto がユーザーのアイデンティティ情報とメールアドレスを適切に取得できるようにするためです。 +**Google Cloud Console での操作：** + +1. **APIs & Services > OAuth consent screen > Scopes** に移動します。 +2. **Add or Remove Scopes** をクリックし、アプリに必要なスコープ (Scopes) のみを選択します： + - 認証 (Authentication)（必須）: + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - API アクセス（任意）：アプリに必要な追加スコープ (Scopes) を追加します（例：Drive、Calendar、YouTube）。利用可能なサービスは [Google API ライブラリ](https://console.cloud.google.com/apis/library) で確認できます。アプリが基本的な権限 (Permissions) 以上の Google API へのアクセスを必要とする場合は、まず Google API ライブラリでアプリが使用する特定の API（例：Google Drive API、Gmail API、Calendar API）を有効にしてください。 +3. **Update** をクリックして選択を確定します。 +4. **Save and Continue** をクリックして変更を適用します。 + +**Logto Google Workspace コネクター (Connector) での操作：** + +1. Logto は、基本的なユーザーアイデンティティ情報を取得するために `openid`、`profile`、`email` のスコープ (Scopes) を自動的に含めます。基本的なユーザー情報のみが必要な場合は、`Scopes` フィールドを空欄のままにできます。 +2. Google からさらに多くのデータをリクエストする場合は、`Scopes` フィールドに追加のスコープ (Scopes)（スペース区切り）を入力します。スコープ (Scopes) の URL は完全な形式で入力してください。例：`https://www.googleapis.com/auth/calendar.readonly` + +:::tip +アプリがこれらのスコープ (Scopes) をリクエストして Google API にアクセスし操作を行う場合は、Logto Google コネクターで **Store tokens for persistent API access** を有効にしてください。詳細は次のセクションを参照してください。 +::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index e0674d2a497..c79dc0b3876 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -Logto のコネクターの `SSO experience` タブで、組織の `email domains` を提供してください。これにより、これらのユーザーに対する認証 (Authentication) 方法として SSO コネクターが有効になります。 +[Google APIs](https://console.cloud.google.com/apis/library) へアクセスし、ユーザーの認可 (Authorization) で操作を行いたい場合、Logto は特定の API スコープとトークンを取得して保存する必要があります。 -指定されたドメインのメールアドレスを持つユーザーは、唯一の認証 (Authentication) 方法として SSO コネクターを使用するようにリダイレクトされます。 +1. 必要なスコープを Google Cloud Console の OAuth 同意画面設定および Logto の Google コネクターに追加します。 +2. Logto の Google コネクターで **永続的な API アクセスのためにトークンを保存** を有効にします。Logto は Google のアクセス トークンおよびリフレッシュ トークンを Secret Vault に安全に保存します。 +3. リフレッシュ トークンが返されるようにするには、Logto の Google コネクターで **オフラインアクセス** を有効にしてください。 -Google Workspace SSO コネクターの詳細については、 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect) をご確認ください。 +:::warning +Logto の `Scope` フィールドに `offline_access` を追加する必要はありません — 追加するとエラーになる場合があります。Google はオフラインアクセスが有効な場合、自動的に `access_type=offline` を使用します。 +::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..be37201f9b5 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +Logto のコネクター「SSO 体験」タブで、組織の `メールドメイン` を入力してください。これにより、指定したユーザーに対して SSO コネクターが認証 (Authentication) 方法として有効になります。 + +指定したドメインのメールアドレスを持つユーザーは、唯一の認証 (Authentication) 方法として SSO コネクターを利用するようリダイレクトされます。 + +Google Workspace SSO コネクターの詳細については、 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect) をご確認ください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 58fed7808ad..b4224b040ca 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -2,9 +2,9 @@ slug: /integrations/oidc-sso sidebar_label: OIDC (エンタープライズ) sidebar_custom_props: - description: Web およびモバイルアプリでのアイデンティティ検証のための OAuth 2.0 に基づいた最新のプロトコル。 + description: Web およびモバイルアプリでのアイデンティティ検証のための OAuth 2.0 を基盤とした最新プロトコル。 logoFilename: 'oidc.svg' -tutorial_name: OIDC enterprise SSO +tutorial_name: OIDC エンタープライズ SSO tutorial_config_name: IdP 上の OIDC アプリケーション --- @@ -13,14 +13,16 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; # OpenID Connect (OIDC) を使用してシングルサインオンを設定する -最小限の設定作業で、このコネクターは OIDC ベースのアイデンティティプロバイダー (IdP) との統合を可能にします。 +最小限の設定で、このコネクターはあらゆる OIDC ベースのアイデンティティプロバイダー (IdP) との統合を可能にします。 -## ステップ 1: IdP に OIDC アプリケーションを作成する \{#step-1-create-an-oidc-application-on-your-idp} +## ステップ 1: IdP 上で OIDC アプリケーションを作成する \{#step-1-create-an-oidc-application-on-your-idp} @@ -28,6 +30,14 @@ import Step3 from './_step-3.mdx'; -## ステップ 3: メールドメインを設定し、SSO コネクターを有効にする \{#step-3-set-email-domains-and-enable-the-sso-connector} +## ステップ 3: スコープの設定（オプション） \{#step-3-configure-scopes-optional} + +## ステップ 4: サードパーティ API へのアクセス用トークンの保存（オプション） \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## ステップ 5: メールドメインの設定と SSO コネクターの有効化 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index fefccb5fb88..2354dc421da 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,6 +1,8 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; ### ステップ 1: IdP で OIDC アプリケーションを作成する \{#step-1-create-an-oidc-application-on-your-idp} @@ -10,6 +12,14 @@ import Step3 from './_step-3.mdx'; -### ステップ 3: メールドメインを設定し、SSO コネクターを有効にする \{#step-3-set-email-domains-and-enable-the-sso-connector} +## ステップ 3: スコープ (Scope) を設定する（任意） \{#step-3-configure-scopes-optional} + +## ステップ 4: サードパーティ API へアクセスするためのトークンを保存する（任意） \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## ステップ 5: メールドメインを設定し、SSO コネクターを有効化する \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index f01ef18280d..ada5a7ba6ce 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -IdP 側で OIDC アプリケーションを正常に作成した後、IdP の設定を Logto に戻す必要があります。`Connection` タブに移動し、次の設定を入力してください： +IdP 側で OIDC アプリケーションの作成に成功した後、IdP の設定情報を Logto 側に提供する必要があります。`Connection` タブに移動し、以下の設定項目を入力してください： -- **Client ID**: IdP によってあなたの OIDC アプリケーションに割り当てられた一意の識別子。この識別子は、OIDC フロー中に Logto がアプリケーションを識別し認証するために使用されます。 -- **Client Secret**: Logto と IdP の間で共有される機密の秘密。この秘密は、OIDC アプリケーションを認証し、Logto と IdP 間の通信を保護するために使用されます。 -- **発行者 (Issuer)**: IdP の一意の識別子である発行者 URL。OIDC アイデンティティプロバイダーの場所を指定します。これは OIDC 設定の重要な部分であり、Logto が必要なエンドポイントを発見するのに役立ちます。 - 設定プロセスを簡単にするために、Logto は必要な OIDC エンドポイントと設定を自動的に取得します。これは、提供された発行者を利用し、IdP の OIDC 発見エンドポイントに呼び出しを行うことで行われます。発行者エンドポイントが有効で正確に設定されていることを確認し、Logto が必要な情報を正しく取得できるようにすることが重要です。 - 取得リクエストが成功した後、発行者セクションの下に解析された IdP 設定が表示されるはずです。 -- **スコープ (Scope)**: OIDC 認証プロセス中に Logto が要求する権限またはアクセスレベルを定義するスペースで区切られた文字列のリスト。スコープパラメーターを使用して、Logto が IdP から要求する情報とアクセスを指定できます。 - スコープパラメーターはオプションです。カスタムスコープ設定に関係なく、Logto は常に `openid`、`profile`、および `email` スコープを IdP に送信します。 - これは、Logto が IdP からユーザーのアイデンティティ情報とメールアドレスを適切に取得できるようにするためです。IdP からより多くの情報を要求するために、スコープパラメーターに追加のスコープを追加することができます。 +- **Client ID**：IdP によって OIDC アプリケーションに割り当てられる一意の識別子です。この識別子は、Logto が OIDC フロー中にアプリケーションを識別し認証するために使用されます。 +- **Client Secret**：Logto と IdP 間で共有される機密のシークレットです。このシークレットは、OIDC アプリケーションの認証および Logto と IdP 間の通信の安全性を確保するために使用されます。 +- **発行者 (Issuer)**：発行者 (Issuer) URL は、IdP の一意の識別子であり、OIDC アイデンティティプロバイダー (IdP) の場所を指定します。これは OIDC 設定の重要な部分であり、Logto が必要なエンドポイントを発見するのに役立ちます。 + 設定プロセスを簡単にするために、Logto は必要な OIDC エンドポイントや設定情報を自動的に取得します。これは、入力した発行者 (Issuer) を利用し、IdP の OIDC ディスカバーエンドポイントにリクエストを送信することで実現されます。Logto が必要な情報を正しく取得できるよう、発行者 (Issuer) エンドポイントが有効かつ正確に設定されていることが重要です。 + 取得リクエストが成功すると、発行者 (Issuer) セクションで解析された IdP 設定情報を確認できます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index b1306f30e49..5f75e7fff91 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -Logto のコネクターの `SSO 体験` タブで、組織の `メールドメイン` を提供してください。これにより、これらのユーザーに対する認証 (Authentication) 方法として SSO コネクターが有効になります。 +スコープ (Scopes) は、アプリがユーザーから要求する権限 (Permissions) を定義し、エンタープライズアカウントからアプリがアクセスできるデータを制御します。 -指定されたドメインのメールアドレスを持つユーザーは、唯一の認証 (Authentication) 方法としてあなたの SSO コネクターを使用するようにリダイレクトされます。 +スコープ (Scopes) の設定には、両方の側での構成が必要です： + +1. **アイデンティティプロバイダー (IdP)**：IdP コンソールで認可 (Authorization) に許可する権限 (Permissions) を設定します + - 一部の IdP では、すべてのパブリックスコープ (Scopes) がデフォルトで有効になっています（追加の操作は不要です） + - その他の IdP では、明示的に権限 (Permissions) を付与する必要があります +2. **Logto エンタープライズコネクター**：Logto OIDC エンタープライズコネクターの設定 > `Scopes` フィールドで、認証 (Authentication) 時にリクエストするスコープ (Scopes) を指定します。 + - Logto は、カスタムスコープ (Scopes) の設定に関係なく、基本的なユーザーアイデンティティ情報を取得するために `openid`、`profile`、`email` スコープ (Scopes) を常に含めます。 + - 追加のスコープ (Scopes)（スペース区切り）を指定することで、IdP からさらに多くの情報をリクエストできます。 + +:::tip +アプリがこれらのスコープ (Scopes) を使用して API にアクセスする必要がある場合は、Logto エンタープライズコネクターで **永続的な API アクセスのためにトークンを保存** を有効にしてください。詳細は次のセクションをご覧ください。 +::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..2c53fd38461 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +アイデンティティプロバイダー (IdP) の API にアクセスし、ユーザーの認可 (Authorization) で操作を行いたい場合、Logto は特定の API スコープ (Scope) を取得し、トークンを保存する必要があります。 + +1. 上記の手順に従い、必要なスコープ (Scope) を **scope** フィールドに追加します。 +2. Logto OIDC エンタープライズコネクターで **永続的な API アクセスのためにトークンを保存** を有効にします。Logto はアクセス トークン (Access token) を Secret Vault に安全に保存します。 +3. **標準** OIDC アイデンティティプロバイダー (IdP) の場合、リフレッシュ トークン (Refresh token) を取得するために `offline_access` スコープ (Scope) を含める必要があります。これにより、ユーザーへの同意画面 (Consent screen) の繰り返し表示を防ぎます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..90f8ec8f09e --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +Logto のコネクター「SSO 体験」タブで、組織の `メールドメイン` を入力してください。これにより、指定したユーザーに対して SSO コネクターが認証 (Authentication) 方法として有効になります。 + +指定したドメインのメールアドレスを持つユーザーは、唯一の認証 (Authentication) 方法として SSO コネクターを利用するようリダイレクトされます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index ee966ff257d..8e25005555c 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -2,40 +2,44 @@ sidebar_position: 2 --- -# デプロイと設定 +# デプロイと構成 -前回の記事では、[Logto を迅速に始める方法](/logto-oss/get-started-with-oss) の基本を紹介しました。この記事では、Logto を本番環境にデプロイするためのベストプラクティスと詳細な設定手順に焦点を当てて、さらに深く掘り下げます。 +前回の記事では、[Logto を素早く始める](/logto-oss/get-started-with-oss) 基本について説明しました。この記事ではさらに深く掘り下げ、本番環境で Logto をデプロイするためのベストプラクティスや詳細な構成手順に焦点を当てます。 ## 環境変数 \{#environment-variables} -デモ (`docker-compose.yml`) では、生成された環境変数のプリセットを使用していますが、これを独自のものに置き換え、複数の Logto インスタンス間で一貫性を保つ必要があります。 +デモ（`docker-compose.yml`）では生成済みの環境変数プリセットを使用していますが、本番環境では独自の値に置き換え、複数の Logto インスタンス間で一貫性を保つ必要があります。 -環境変数を直接設定するか、Logto プロジェクトのルートに `.env` ファイルを配置できます。Docker でテストしている場合は、`/etc/logto` に生成された `.env` を確認してください。 +環境変数は直接設定するか、Logto プロジェクトのルートに `.env` ファイルを配置できます。Docker でテストする場合は、イメージ内 `/etc/logto` に生成される `.env` を確認してください。 ### 必須項目 \{#essentials} - `DB_URL` Logto データベース用の [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 - `PORT` Logto がリッスンするポート。デフォルトは `3001`。 -- `ENDPOINT` 本番用にカスタムドメインを指定できます（例：`ENDPOINT=https://logto.domain.com`）。これは [OIDC 発行者識別子](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) の値にも影響します。 +- `ENDPOINT` 本番環境用にカスタムドメインの URL を指定できます（例：`ENDPOINT=https://logto.domain.com`）。これは [OIDC 発行者識別子](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) の値にも影響します。 -**管理コンソールを有効にする** +**管理コンソールの有効化** - `ADMIN_PORT` Logto 管理コンソールがリッスンするポート。デフォルトは `3002`。 -- `ADMIN_ENDPOINT` 本番用にカスタムドメインを指定できます（例：`ADMIN_ENDPOINT=https://admin.domain.com`）。これは管理コンソールのリダイレクト URI の値にも影響します。 +- `ADMIN_ENDPOINT` 本番環境用にカスタムドメインの URL を指定できます（例：`ADMIN_ENDPOINT=https://admin.domain.com`）。これは管理コンソールのリダイレクト URI の値にも影響します。 -**管理コンソールを無効にする** +**管理コンソールの無効化** -- `ADMIN_DISABLE_LOCALHOST` 管理コンソールのポートを閉じるには `1` または `true` に設定します。`ADMIN_ENDPOINT` が設定されていない場合、管理コンソールは完全に無効になります。 +- `ADMIN_DISABLE_LOCALHOST` 管理コンソール用ポートを閉じるには `1` または `true` に設定します。`ADMIN_ENDPOINT` が未設定の場合、管理コンソールが完全に無効になります。 -環境変数の詳細については、[設定](/concepts/core-service/configuration/) を参照してください。 +環境変数の詳細については [構成](/concepts/core-service/configuration/) を参照してください。 + +**Secret Vault の有効化** + +- [Secret Vault](/secret-vault) を利用するには、`SECRET_VAULT_KEK` に Key Encryption Key (KEK) の base64 エンコード文字列を設定してください。これは Secret Vault 内の Data Encryption Key (DEK) を暗号化するために使用されます。AES-256（32 バイト）推奨。例：`crypto.randomBytes(32).toString('base64')`。 ### HTTPS \{#https} -Node.js を使用して直接 HTTPS を提供するか、Node.js の前に HTTPS プロキシ / バランサーを設定できます。詳細は [HTTPS の有効化](/concepts/core-service/configuration/#enabling-https) を参照してください。 +Node.js で直接 HTTPS を提供するか、Node.js の前段に HTTPS プロキシ / バランサーを設定できます。詳細は [HTTPS の有効化](/concepts/core-service/configuration/#enabling-https) を参照してください。 ### リバースプロキシ \{#reverse-proxy} -サーバーでリバースプロキシを使用したい場合、例えば Nginx や Apache では、プロキシパス設定で 3001 と 3002 ポートを別々にマッピングする必要があります。Nginx を使用していると仮定し、Logto 認証エンドポイントがポート 3001 で、Logto 管理コンソールがポート 3002 で動作している場合、nginx.conf に次の設定を追加します： +サーバーでリバースプロキシ（Nginx や Apache など）を利用する場合、プロキシパス設定で 3001 および 3002 ポートを個別にマッピングする必要があります。Nginx を使用し、Logto 認証エンドポイントが 3001 ポート、管理コンソールが 3002 ポートで動作している場合、nginx.conf に以下の設定を追加します： ``` server { @@ -58,7 +62,7 @@ server { } ``` -次に、管理コンソール用に同様の設定を追加します： +次に、管理コンソール用にも同様の設定を追加します： ``` server { @@ -81,23 +85,23 @@ server { } ``` -Nginx の設定をリロードして最新の変更を反映させます： +Nginx 設定をリロードして最新の変更を反映させます： ``` nginx -s reload ``` -これで準備完了です。ブラウザを開いて `https://admin.your-domain.com` にアクセスすると、Logto のウェルカムページが表示されるはずです。 +これで準備完了です。ブラウザで `https://admin.your-domain.com` にアクセスすると、Logto のウェルカムページが表示されるはずです。 ## コンテナ化 \{#containerization} -本番環境では、Docker を使用して Logto をコンテナ化することができます。プロジェクトのルートディレクトリに Dockerfile が見つかります。複数の Logto インスタンスを実行したい場合、例えば Kubernetes クラスターに Logto をデプロイする場合、追加の手順が必要です。 +本番環境では、Docker を使って Logto をコンテナ化できます。プロジェクトのルートディレクトリに Dockerfile があります。複数の Logto インスタンスを実行したい場合（例：Kubernetes クラスターにデプロイする場合）、追加の手順が必要です。 -### 共有コネクタフォルダ \{#shared-connectors-folder} +### コネクタ共有フォルダー \{#shared-connectors-folder} -デフォルトでは、Logto は `core` フォルダのルートディレクトリに `connectors` フォルダを作成します。Logto の複数のインスタンス間でフォルダを共有することをお勧めします。`packages/core/connectors` フォルダをコンテナにマウントし、`npm run cli connector add -- --official` を実行してコネクタをデプロイします。 +デフォルトでは、Logto は `core` フォルダーのルートに `connectors` フォルダーを作成します。複数インスタンス間でこのフォルダーを共有することを推奨します。`packages/core/connectors` フォルダーをコンテナにマウントし、`npm run cli connector add -- --official` を実行してコネクターをデプロイしてください。 -Kubernetes の最小例 `deployment` は次のとおりです： +Kubernetes 用の最小限の `deployment` 例は以下の通りです： ```yaml apiVersion: extensions/v1beta1 @@ -130,21 +134,21 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -この例では、ボリュームとして空のディレクトリを作成し、それをコンテナにマウントします。次に、init コンテナで `npm run cli connector add -- --official` を実行してコネクタをダウンロードします。最後に、すべてのコンテナが公式コネクタを含む同じコネクタフォルダを共有します。 +この例では、空のディレクトリをボリュームとして作成し、それをコンテナにマウントします。次に、init コンテナで `npm run cli connector add -- --official` を実行してコネクターをダウンロードします。最終的に、すべてのコンテナが公式コネクター入りの同じコネクターフォルダーを共有します。 :::note -これは例の yaml です。Logto を実行するには、環境変数を適切に設定する必要があります。 +これはサンプル yaml です。Logto を動作させるには、環境変数を適切に設定してください。 ::: -本番環境では、「空のディレクトリ」ボリュームを永続ボリュームに置き換え、自分の方法で「init」ジョブを実行できます。自分が何をしているかを理解しているはずです！ +本番環境では "empty dir" ボリュームを永続ボリュームに置き換えたり、"init" ジョブを独自の方法で実行したりできます。ご自身の運用に合わせて調整してください。 -### データベースの変更 \{#database-alteration} +### データベース変更 \{#database-alteration} -コネクタと同様に、データベースの変更は単一のインスタンスで実行する必要があります。ジョブを使用して変更スクリプトを実行できます。 +コネクターと同様に、データベースの変更も単一インスタンスで実行する必要があります。ジョブを使って変更スクリプトを実行できます。 -`CI=true` 環境変数は、非対話的に変更を実行する場合に必要です。 +非対話型で変更を実行する場合は `CI=true` 環境変数が必要です。 ```yaml apiVersion: batch/v1 @@ -171,4 +175,4 @@ spec: restartPolicy: Never ``` -変更コマンドの詳細については、[データベースの変更](/logto-oss/using-cli/database-alteration/) を参照してください。 +変更コマンドの詳細は [データベース変更](/logto-oss/using-cli/database-alteration/) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..b3bc639c97d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# シークレットボールト (Secret Vault) + +Logto のシークレットボールト (Secret Vault) は、アクセス トークン、API キー、パスコード、その他保護が必要な機密情報など、機密性の高いユーザーデータを安全に保存するために設計されています。これらのシークレットは、ユーザーに代わってサードパーティサービスへアクセスする際によく使用されるため、安全な保存が不可欠です。 + +## 暗号化方式 \{#encryption-scheme} + +機密データを保護するため、シークレットボールト (Secret Vault) では **データ暗号化キー (DEK)** と **キー暗号化キー (KEK)** に基づく堅牢な暗号化方式を採用しています。 + +- **シークレットごとの暗号化**：各シークレットは固有の DEK で暗号化されるため、仮に 1 つのキーが漏洩しても他のシークレットは安全に保たれます。 +- **キーラッピング**：DEK 自体は KEK で暗号化（「ラッピング」）され、システムによって安全に管理・保存されます。 +- **多層セキュリティ**：この 2 段階のアプローチにより、システムの一部が侵害された場合でも、DEK と KEK の両方がなければシークレットにアクセスできません。 +- **露出の最小化**：シークレットは本当に必要なときだけ復号されるため、偶発的な露出リスクが低減され、機密データの取り扱いにおけるベストプラクティスに沿っています。 + +この多層暗号化モデルにより、ユーザーの最も機密性の高い認証情報やトークンが強力に保護され、必要なときには安全にアクセスできます。 + +## シークレットの種類 \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +現在、標準でサポートされているシークレットの種類はフェデレーテッドトークンセット (Federated token set) のみです。ただし、シークレットボールト (Secret Vault) はあらゆる種類の機密情報に対応できるよう設計されています。追加のシークレットタイプへの対応が必要な場合は、 [お問い合わせ](https://logto.io/contact) ください — 喜んでサポートいたします。 +::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..cf16e6ad53b --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,232 @@ +--- +id: federated-token-set +title: フェデレーテッドトークンセット +sidebar_label: フェデレーテッドトークンセット +--- + +import Availability from '@components/Availability'; + + + +フェデレーテッドトークンセットは、Logto の Secret Vault に保存されるシークレットタイプであり、フェデレーテッドなサードパーティアイデンティティプロバイダーによって発行されたアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) を安全に管理するために使用されます。ユーザーがソーシャルまたはエンタープライズシングルサインオン (SSO) コネクター経由で認証 (Authentication) すると、Logto は発行されたトークンを Vault に保存します。これらのトークンは後で取得でき、再認証なしでユーザーの代わりにサードパーティ API へアクセスできます。 + +## フェデレーテッドトークンストレージの有効化 \{#enable-federated-token-storage} + +### ソーシャルコネクター \{#social-connectors} + +:::Info +この機能はトークンストレージをサポートするコネクターのみで利用可能です。現在サポートされているコネクターは次の通りです：[GitHub](/integrations/github)、[Google](/integrations/google)、[Facebook](/integrations/facebook)、[Standard OAuth 2.0](/integrations/oauth2)、[Standard OIDC](/integrations/oidc)。今後、追加のコネクターにも順次対応予定です。 +::: + +1. コンソール > コネクター > ソーシャルコネクター + に移動します。 +2. フェデレーテッドトークンストレージを有効にしたいソーシャルコネクターを選択します。 +3. 「設定」ページで、**永続的な API アクセスのためにトークンを保存** オプションを有効にします。 + +### エンタープライズ SSO コネクター \{#enterprise-sso-connectors} + +:::Info +トークンストレージはすべての OIDC エンタープライズコネクターで利用可能です。 +::: + +1. コンソール > エンタープライズ SSO に移動します。 +2. フェデレーテッドトークンストレージを有効にしたいエンタープライズ SSO コネクターを選択します。 +3. 「SSO 体験」タブで、**永続的な API アクセスのためにトークンを保存** オプションを有効にします。 + +変更内容を必ず保存してください。 + +## トークンストレージ \{#token-storage} + +フェデレーテッドトークンストレージを有効にすると、ユーザーがソーシャルまたはエンタープライズ SSO コネクター経由で認証 (Authentication) するたびに、Logto はフェデレーテッドアイデンティティプロバイダーによって発行されたアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) を自動的に保存します。これには次が含まれます： + +- [ソーシャルサインイン・サインアップ](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [エンタープライズ SSO サインイン・サインアップ](/end-user-flows/enterprise-sso) +- [アカウント API 経由でのソーシャルアカウント連携](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +保存されたトークンはユーザーのソーシャルまたはエンタープライズ SSO アイデンティティに紐づけられ、後で再認証なしで API アクセスのためにトークンを取得できます。 + +### トークンストレージの状態確認 \{#checking-token-storage-status} + +Logto コンソールでユーザーのフェデレーテッドトークンストレージの状態を確認できます： + +1. コンソール > ユーザー に移動します。 +2. 確認したいユーザーをクリックします。ユーザー詳細ページに移動します。 +3. **接続** セクションまでスクロールします。このエリアにはユーザーに紐づくすべてのソーシャルおよびエンタープライズ SSO 接続が一覧表示されます。 +4. 各接続エントリーには、その接続にトークンが保存されているかどうかを示すトークンステータスラベルが表示されます。 +5. 接続エントリーをクリックすると、保存されたアクセス トークン (Access token) のメタデータやリフレッシュ トークン (Refresh token) の有無（利用可能な場合）など、詳細を確認できます。 + +また、Management API を通じてユーザーのサードパーティアイデンティティやトークンストレージの状態を確認することも可能です： + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`：指定したコネクターターゲット（例：`github`、`google` など）に紐づくユーザーのソーシャルアイデンティティとトークンストレージの状態を取得します。 +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`：指定した SSO コネクター ID に紐づくユーザーのエンタープライズ SSO アイデンティティとトークンストレージの状態を取得します。 + +### トークンストレージの状態 \{#token-storage-status} + +- **アクティブ**：アクセス トークン (Access token) が保存されており有効です。 +- **期限切れ**：アクセス トークン (Access token) は保存されていますが、期限切れです。リフレッシュ トークン (Refresh token) が利用可能な場合、新しいアクセス トークン (Access token) を取得できます。 +- **非アクティブ**：この接続にアクセス トークン (Access token) が保存されていません。ユーザーがこの接続で認証 (Authentication) していない場合や、トークンストレージが削除された場合に発生します。 +- **該当なし**：コネクターがトークンストレージをサポートしていません。 + +### トークンメタデータ \{#token-metadata} + +データの整合性とセキュリティのため、すべてのトークンは Secret Vault に保存される前に暗号化されます。実際のトークン値は、適切な認可 (Authorization) を持つエンドユーザーのみがアクセスできます。一方、開発者はトークンセットのメタデータのみ取得でき、機密情報を露出せずに保存状態を把握できます。 + +- `createdAt`：接続が初めて確立され、トークンセットが Secret Vault に初回保存されたタイムスタンプ。 +- `updatedAt`：トークンセットが最後に更新された時刻。 + - リフレッシュ トークン (Refresh token) がない場合、この値は **createdAt** と同じです。 + - リフレッシュ トークン (Refresh token) がある場合、この値はアクセス トークン (Access token) が最新でリフレッシュされた時刻を示します。 +- `hasRefreshToken`：リフレッシュ トークン (Refresh token) が利用可能かどうかを示します。 + コネクターがオフラインアクセスをサポートし、認可 (Authorization) リクエストが適切に構成されている場合、Logto はアイデンティティプロバイダーから発行されたリフレッシュ トークン (Refresh token) をアクセス トークン (Access token) とともに保存します。 + アクセス トークン (Access token) が期限切れで有効なリフレッシュ トークン (Refresh token) が存在する場合、ユーザーが接続先プロバイダーへのアクセスを要求するたびに、Logto は保存されたリフレッシュ トークン (Refresh token) を使って新しいアクセス トークン (Access token) の取得を自動的に試みます。 +- `expiresAt`：アクセス トークン (Access token) の推定有効期限（**秒単位**）。 + これはアイデンティティプロバイダーのトークンエンドポイントから返される `expires_in` 値に基づいて計算されます。（このフィールドはプロバイダーがトークンレスポンスに `expires_in` を含めている場合のみ利用可能です。） +- `scope`：アクセス トークン (Access token) のスコープ (Scope)。アイデンティティプロバイダーによって付与された権限 (Permissions) を示します。 + 保存されたアクセス トークン (Access token) でどのような操作が可能かを把握するのに役立ちます。（このフィールドはプロバイダーがトークンレスポンスに `scope` を含めている場合のみ利用可能です。） +- `tokenType`：アクセス トークン (Access token) のタイプ。通常は "Bearer" です。 + （このフィールドはプロバイダーがトークンレスポンスに `token_type` を含めている場合のみ利用可能です。） + +## トークン取得 \{#token-retrieval} + +トークンストレージが有効化され、トークンが Logto の Secret Vault に安全に保存されると、エンドユーザーは Logto の [ユーザーアカウント API](/end-user-flows/account-settings/by-account-api) を統合することで、クライアントアプリケーションからサードパーティのアクセス トークン (Access token) を取得できます。 + +- `GET /my-account/identities/:target/access-token`：コネクターターゲット（例：github、google）を指定してソーシャルアイデンティティのアクセス トークン (Access token) を取得します。 + +- `GET /my-account/sso-identities/:connectorId/access-token`：コネクター ID を指定してエンタープライズ SSO アイデンティティのアクセス トークン (Access token) を取得します。 + +:::info +Logto 発行のアクセス トークン (Access token) を使って [Account API を有効化](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) および [アクセス](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) する方法を学べます。 +::: + +### トークンローテーション \{#token-rotation} + +トークン取得エンドポイントは次のレスポンスを返します： + +- `200` OK：アクセス トークン (Access token) の取得に成功し、まだ有効な場合。 +- `404` Not Found：指定したターゲットまたはコネクター ID に紐づくソーシャルまたはエンタープライズ SSO アイデンティティが存在しない場合、またはアクセス トークン (Access token) が保存されていない場合。 +- `401` Unauthorized：アクセス トークン (Access token) が期限切れの場合。 + +アクセス トークン (Access token) が期限切れでリフレッシュ トークン (Refresh token) が利用可能な場合、Logto は自動的にアクセス トークン (Access token) のリフレッシュを試み、新しいアクセス トークン (Access token) をレスポンスで返します。Secret Vault のトークンストレージも新しいアクセス トークン (Access token) とそのメタデータで更新されます。 + +## トークンストレージの削除 \{#token-storage-deletion} + +フェデレーテッドトークンストレージは各ユーザーのソーシャルまたはエンタープライズ SSO 接続に直接紐づいています。つまり、次の場合に保存されたトークンセットは自動的に削除されます： + +- 関連するソーシャルまたはエンタープライズ SSO アイデンティティがユーザーアカウントから削除された場合 +- ユーザーアカウントがテナントから削除された場合 +- ソーシャルまたはエンタープライズ SSO コネクターがテナントから削除された場合 + +### トークンの失効 \{#revoking-tokens} + +ユーザーのサードパーティトークンセットを手動で削除してアクセスを失効させることもできます： + +- コンソールから： + ユーザーのアイデンティティ詳細ページに移動します。**アクセス トークン (Access token)** セクション（トークンストレージが利用可能な場合）までスクロールし、セクション末尾の **トークンを削除** ボタンをクリックします。 +- Management API 経由： + - `DELETE /api/secret/:id`：ユーザーアイデンティティ詳細から取得できる ID で特定のシークレットを削除します。 + +トークンセットを失効させると、ユーザーは再度サードパーティプロバイダーで認証 (Authentication) し、新しいアクセス トークン (Access token) を取得しない限り、サードパーティ API へアクセスできなくなります。 + +## 再認証とトークン更新 \{#reauthentication-and-token-renewal} + +保存されたアクセス トークン (Access token) が期限切れの場合や、アプリケーションが追加の API スコープ (Scope) を要求する必要がある場合、エンドユーザーはサードパーティプロバイダーで再認証し、新しいアクセス トークン (Access token) を取得できます—Logto への再サインインは不要です。 +これは Logto の [ソーシャル認証 API](https://openapi.logto.io/operation/operation-createverificationbysocial) を通じて実現でき、ユーザーはフェデレーテッドなソーシャル認可 (Authorization) フローを再開し、保存されたトークンセットを更新できます。 + +:::note +フェデレーテッド認可 (Authorization) の再実行は現在ソーシャルコネクターに限定されています。 +エンタープライズ SSO コネクターの場合、再認証とトークン更新にはユーザーが再度 Logto の認証 (Authentication) フローを開始する必要があります。サインイン後にエンタープライズ SSO プロバイダーと直接再認可 (Authorization) することは現在サポートされていません。 +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as ユーザー + participant Logto as Logto + participant Provider as サードパーティプロバイダー + + User->>Logto: post /api/verification/social + Logto->>User: サードパーティプロバイダーへリダイレクト + User->>Provider: 認証 (Authentication) および認可 (Authorization) + Provider->>User: 認可コード付きでリダイレクト + User->>Logto: post /api/verification/social/verify（認可コード付き） + Logto->>User: ソーシャル認証 ID を返す + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. ユーザーは `POST /api/verification/social` エンドポイントを呼び出してソーシャル認証リクエストを開始します。追加の権限 (Permissions) を要求するためにカスタムスコープ (Scope) を指定することもできます。 + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**：Logto によって発行されたユーザーのアクセス トークン (Access token)。 + - **connectorId**：Logto 内のソーシャルコネクター ID。 + - **redirectUri**：認証 (Authentication) 後にユーザーをアプリケーションへリダイレクトする URI。この URI はプロバイダーのアプリケーション設定に登録する必要があります。 + - **scope**：（オプション）サードパーティプロバイダーから追加の権限 (Permissions) を要求するためのカスタムスコープ (Scope)。指定しない場合、コネクターで設定されたデフォルトスコープが使用されます。 + +2. Logto は新しいソーシャル認証レコードを作成し、ユーザーをサードパーティプロバイダーへリダイレクトするための認可 (Authorization) URL とともにソーシャル認証 ID を返します。 + + レスポンス例： + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. ユーザーを認可 (Authorization) URL へリダイレクトします。ユーザーはサードパーティプロバイダーで認証 (Authentication) し、権限 (Permissions) を付与します。 + +4. サードパーティプロバイダーは認可コード付きでユーザーをクライアントアプリケーションへリダイレクトします。 + +5. 認可コールバックを処理し、認可コードを Logto の認証エンドポイントへ転送します： + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**：Logto によって発行されたユーザーのアクセス トークン (Access token)。 + - **verificationRecordId**：前のステップで返されたソーシャル認証 ID。 + - **connectorData**：認可コードやコールバック時にサードパーティプロバイダーから返されたその他のデータ。 + + :::note + CSRF 攻撃を防ぐため、`state` パラメーターの検証を忘れないでください。 + ::: + +6. Logto は認可コードを検証し、サードパーティプロバイダーから新しいアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) を取得し、レスポンスでソーシャル認証 ID を返します。 + +7. 最後に、`PATCH /my-account/identities/:target/access-token` エンドポイントにソーシャル認証 ID を指定してユーザーのトークンストレージを更新します： + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**：Logto によって発行されたユーザーのアクセス トークン (Access token)。 + - **socialVerificationId**：前のステップで返された検証済みソーシャル認証レコード ID。 + + これにより、Logto の Secret Vault 内のユーザーのトークンセットストレージが新しいアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) で更新され、ユーザーは再度 Logto にサインインすることなくサードパーティ API へアクセスできるようになります。 + + 更新されたアクセス トークン (Access token) が返されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 02273566998..b80524ac167 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -8,41 +8,53 @@ sidebar_position: 4 ## パーソナルアクセストークンの管理 \{#managing-personal-access-tokens} -### コンソールを使用する場合 \{#using-console} +### コンソールの利用 \{#using-console} コンソール > ユーザー管理 のユーザー詳細ページでパーソナルアクセストークンを管理できます。「認証 -(Authentication)」カードで、パーソナルアクセストークンの一覧を確認したり、新規作成したりできます。 +(Authentication)」カードで、パーソナルアクセストークンの一覧を確認したり、新規作成が可能です。 -### Management API を使用する場合 \{#using-management-api} +### Management API の利用 \{#using-management-api} -[Management API](/integrate-logto/interact-with-management-api/) をセットアップした後、[API エンドポイント](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) を利用してパーソナルアクセストークンの作成、一覧表示、削除が可能です。 +[Management API](/integrate-logto/interact-with-management-api/) をセットアップした後、[API エンドポイント](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) を利用してパーソナルアクセストークンの作成、一覧取得、削除ができます。 -## PAT を使ってアクセス トークン (Access token) を付与する \{#use-pats-to-grant-access-tokens} +## PAT を使ってアクセス トークン (Access tokens) を付与する \{#use-pats-to-grant-access-tokens} PAT を作成した後、トークンエクスチェンジエンドポイントを利用してアプリケーションにアクセス トークン (Access token) を付与できます。 +:::tip トークンフローの等価性 + +PAT を利用して取得したアクセス トークン (Access token) は、標準の `refresh_token` フローで取得したトークンと**同一の動作**をします。つまり： + +- **組織コンテキスト**：PAT で取得したトークンは、リフレッシュ トークン (Refresh token) フローと同じ組織権限やスコープをサポートします +- **認可フロー**：PAT で交換したアクセス トークン (Access token) は [組織権限](/authorization/organization-permissions) や [組織レベルの API リソース](/authorization/organization-level-api-resources) に利用できます +- **トークン検証**：同じ検証ロジックが適用されます — 初期の grant type だけが異なります + +組織を扱う場合、PAT でもリフレッシュ トークン (Refresh token) でもアクセスパターンや権限は同じです。 + +::: + ### リクエスト \{#request} -アプリケーションは、HTTP POST メソッドを使用して、テナントの [トークンエンドポイント](/integrate-logto/application-data-structure#token-endpoint) に特別なグラントタイプで [トークンエクスチェンジリクエスト](https://auth.wiki/authorization-code-flow#token-exchange-request) を送信します。HTTP リクエストのエンティティボディには `application/x-www-form-urlencoded` 形式で次のパラメータが含まれます。 +アプリケーションは、HTTP POST メソッドを使い、特別な grant type でテナントの [トークンエンドポイント](/integrate-logto/application-data-structure#token-endpoint) へ [トークンエクスチェンジリクエスト](https://auth.wiki/authorization-code-flow#token-exchange-request) を送信します。HTTP リクエストのエンティティボディには `application/x-www-form-urlencoded` 形式で次のパラメータを含めます。 1. `client_id`: 必須。アプリケーションのクライアント ID。 -2. `grant_type`: 必須。このパラメータの値は `urn:ietf:params:oauth:grant-type:token-exchange` で、トークンエクスチェンジが実行されていることを示します。 -3. `resource`: 任意。リソースインジケーター。他のトークンリクエストと同様です。 -4. `scope`: 任意。リクエストされたスコープ。他のトークンリクエストと同様です。 +2. `grant_type`: 必須。このパラメータの値は `urn:ietf:params:oauth:grant-type:token-exchange` で、トークンエクスチェンジを示します。 +3. `resource`: 任意。他のトークンリクエストと同じリソースインジケーター。 +4. `scope`: 任意。他のトークンリクエストと同じリクエストスコープ。 5. `subject_token`: 必須。ユーザーの PAT。 6. `subject_token_type`: 必須。`subject_token` パラメータで提供されるセキュリティトークンのタイプ。このパラメータの値は `urn:logto:token-type:personal_access_token` でなければなりません。 ### レスポンス \{#response} -トークンエクスチェンジリクエストが成功すると、テナントのトークンエンドポイントはユーザーのアイデンティティを表すアクセス トークン (Access token) を返します。レスポンスには、HTTP レスポンスのエンティティボディに `application/json` 形式で次のパラメータが含まれます。 +トークンエクスチェンジリクエストが成功すると、テナントのトークンエンドポイントはユーザーのアイデンティティを表すアクセス トークン (Access token) を返します。レスポンスは `application/json` 形式で、HTTP レスポンスのエンティティボディに次のパラメータを含みます。 -1. `access_token`: 必須。ユーザーのアクセス トークン (Access token)。`authorization_code` や `refresh_token` など他のトークンリクエストと同様です。 +1. `access_token`: 必須。ユーザーのアクセス トークン (Access token)。`authorization_code` や `refresh_token` など他のトークンリクエストと同じです。 2. `issued_token_type`: 必須。発行されたトークンのタイプ。このパラメータの値は `urn:ietf:params:oauth:token-type:access_token` でなければなりません。 3. `token_type`: 必須。トークンのタイプ。このパラメータの値は `Bearer` でなければなりません。 -4. `expires_in`: 必須。アクセス トークン (Access token) の有効期間（秒単位）。 +4. `expires_in`: 必須。アクセス トークン (Access token) の有効期間（秒）。 5. `scope`: 任意。アクセス トークン (Access token) のスコープ。 -### トークンエクスチェンジの例 \{#example-token-exchange} +### トークンエクスチェンジ例 \{#example-token-exchange} ``` POST /oidc/token HTTP/1.1 @@ -86,7 +98,7 @@ Content-Type: application/json ## 関連リソース \{#related-resources} - パーソナルアクセストークンとは？どのような場合にパーソナルアクセストークンを使うべきか？ + パーソナルアクセストークンとは？どんなときにパーソナルアクセストークンを使うべき？ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index 9a22f537a61..16fb3a232bf 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -11,16 +11,18 @@ Logto は、他のプラットフォームから既存ユーザーを手動で 始める前に、Logto の [ユーザースキーマ](/user-management/user-data/#user-profile) を見てみましょう。ユーザースキーマには、次の 3 つの部分があります： 1. **基本データ**：ユーザープロファイルからの基本情報で、既存のユーザープロファイルのデータとマッチさせることができます。 -2. **カスタムデータ**：追加のユーザー情報を保存します。基本データにマッチできないファイルなどを保存するのに利用できます。 +2. **カスタムデータ**：追加のユーザー情報を保存します。基本データにマッチしないファイルなどを保存するのに利用できます。 3. **ソーシャルアイデンティティ**：ソーシャルサインインから取得したユーザー情報を保存します。 -既存のユーザープロファイルから **基本データ** および **カスタムデータ** へ情報をマッピングするためのマップを作成できます。ソーシャルサインインの場合は、ソーシャルアイデンティティをインポートするために追加の手順が必要です。詳細は [Link social identity to user](https://openapi.logto.io/operation/operation-createuseridentity) の API を参照してください。 +既存のユーザープロファイルから **基本データ** および **カスタムデータ** へ情報をマッピングするためのマップを作成できます。ソーシャルサインインの場合は、ソーシャルアイデンティティをインポートするために追加の手順が必要です。詳細は [ソーシャルアイデンティティをユーザーにリンクする](https://openapi.logto.io/operation/operation-createuseridentity) API を参照してください。 ## パスワードハッシュ化 \{#password-hashing} Logto は [Argon2](https://en.wikipedia.org/wiki/Argon2) を使ってユーザーのパスワードをハッシュ化していますが、移行の利便性のために `MD5`、`SHA1`、`SHA256`、`Bcrypt` など他のアルゴリズムもサポートしています。これらのアルゴリズムは安全ではないと考えられており、該当するパスワードハッシュはユーザーが初めてサインインに成功した際に Argon2 へ移行されます。 -他のハッシュアルゴリズムやソルトを使用している場合は、`passwordAlgorithm` を `Legacy` に設定できます。これにより、Node.js でサポートされている任意のハッシュアルゴリズムを利用できます。サポートされているアルゴリズムの一覧は [Node.js crypto ドキュメント](https://nodejs.org/api/crypto.html#cryptogethashes) で確認できます。この場合、`passwordDigest` はハッシュアルゴリズムやその他のアルゴリズム固有のパラメータを含む JSON 文字列になります。 +他のハッシュアルゴリズムやソルトを使用している場合は、`passwordAlgorithm` を `Legacy` に設定できます。これにより、Node.js でサポートされている任意のハッシュアルゴリズムを利用できます。サポートされているアルゴリズムの一覧は [Node.js crypto ドキュメント](https://nodejs.org/api/crypto.html#cryptogethashes) で確認できます。この場合、`passwordDigest` はハッシュアルゴリズムやその他のアルゴリズム固有のパラメータを含む JSON 文字列となります。 + +### 一般的な Legacy フォーマット \{#general-legacy-format} JSON 文字列のフォーマットは次の通りです： @@ -30,7 +32,7 @@ JSON 文字列のフォーマットは次の通りです： 引数内で実際のパスワード値のプレースホルダーとして `@` を使用できます。 -例えば、SHA256 とソルトを使っている場合、パスワードは次の形式で保存できます： +例えば、SHA256 とソルトを使っている場合、パスワードは次のような形式で保存できます： ```json ["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"] @@ -44,10 +46,40 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### PBKDF2 サポート \{#pbkdf2-support} + +Logto は [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) を特別にサポートしています。 + +PBKDF2 でハッシュ化されたパスワードを移行するには、`passwordAlgorithm` を `Legacy` に設定し、`passwordDigest` を次のようにフォーマットします： + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +各パラメータの意味は以下の通りです： + +- **`salt`**：元のハッシュ化で使用したソルト値 +- **`iterations`**：イテレーション回数（例: `"1000"`） +- **`keylen`**：導出キーのバイト長（例: `"20"`） +- **`digest`**：使用したハッシュ関数（例: `"sha512"`、`"sha256"`、`"sha1"`） +- **`@`**：実際のパスワード値のプレースホルダー +- **`expected_hashed_value`**：16 進数文字列としての期待されるハッシュ結果 + +**移行ペイロード例：** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## 移行手順 \{#steps-to-migrate} 1. **ユーザーデータの準備** - まず既存プラットフォームからユーザーデータをエクスポートし、Logto のユーザースキーマに情報をマッピングします。マッピングしたデータは JSON 形式で準備することを推奨します。以下はユーザーデータの例です： + まず既存プラットフォームからユーザーデータをエクスポートし、Logto のユーザースキーマに情報をマッピングします。マッピング済みデータは JSON 形式で準備することを推奨します。ユーザーデータの例は以下の通りです： ```json [ @@ -65,9 +97,9 @@ const expectedHashedValue = hash.digest('hex'); ``` 2. **Logto テナントの作成** - Logto でテナントをセットアップする必要があります。Logto Cloud または Logto OSS のいずれかを利用できます。まだセットアップしていない場合は、[Logto cloud のセットアップ](/introduction/set-up-logto-cloud/#create-logto-tenant) ガイドを参照してください。 + Logto でテナントをセットアップする必要があります。Logto Cloud または Logto OSS のいずれかを利用できます。まだセットアップしていない場合は、[Logto Cloud のセットアップ](/introduction/set-up-logto-cloud/#create-logto-tenant) ガイドを参照してください。 3. **Management API の接続設定** - Management API を使ってユーザーデータをインポートします。開発環境での接続方法については [Management API](/integrate-logto/interact-with-management-api) を参照してください。 + Management API を使ってユーザーデータをインポートします。開発環境での接続方法は [Management API](/integrate-logto/interact-with-management-api) を参照してください。 4. **ユーザーデータのインポート** ユーザーデータを 1 件ずつインポートするスクリプトを用意することを推奨します。[create user](https://openapi.logto.io/operation/operation-createuser) API を呼び出してユーザーデータをインポートします。スクリプト例は以下の通りです： @@ -88,7 +120,7 @@ const expectedHashedValue = hash.digest('hex'); // レートリミット回避のため少し待機 await new Promise((resolve) => setTimeout(resolve, 200)); } catch (error) { - console.error(`Failed to import user ${user.username}: ${error.message}`); + console.error(`ユーザー ${user.username} のインポートに失敗しました: ${error.message}`); } } }; @@ -96,9 +128,9 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -API エンドポイントにはレートリミットがあるため、各リクエストの間に待機時間を設けてください。詳細は [レートリミット](/integrate-logto/interact-with-management-api/#rate-limit) ページを確認してください。 +API エンドポイントにはレートリミットがあるため、各リクエストの間にスリープを入れてレートリミットを回避してください。詳細は [レートリミット](/integrate-logto/interact-with-management-api/#rate-limit) ページをご確認ください。 -大量のユーザーデータ（10 万件以上）がある場合は、[こちらからご連絡ください](https://logto.io/contact) 。レートリミットの引き上げが可能です。 +大量のユーザーデータ（10 万件以上）がある場合は、[こちらからお問い合わせください](https://logto.io/contact) 。レートリミットの引き上げが可能です。 ## 関連リソース \{#related-resources} diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/ko/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index 11fe8927797..d1f0a5429a8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -7,9 +7,9 @@ Logto는 환경 변수를 다음 순서로 처리합니다: - 시스템 환경 변수 -- 프로젝트 루트의 `.env` 파일, [dotenv](https://github.com/motdotla/dotenv#readme) 형식을 따릅니다. +- 프로젝트 루트의 `.env` 파일 ([dotenv](https://github.com/motdotla/dotenv#readme) 형식 준수) -따라서 시스템 환경 변수는 `.env`의 값을 덮어씁니다. +따라서 시스템 환경 변수가 `.env`의 값을 덮어씁니다. ### 변수 {#variables} @@ -17,43 +17,44 @@ Logto는 환경 변수를 다음 순서로 처리합니다: 프로젝트 루트에서 `npm start`로 Logto를 실행하면, `NODE_ENV`는 항상 `production`입니다. ::: -기본 값에서, `protocol`은 HTTPS 설정에 따라 `http` 또는 `https`가 됩니다. - -| Key | Default Value | Type | Description | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto가 실행되는 환경의 종류입니다. | -| PORT | `3001` | `number` | Logto가 수신하는 로컬 포트입니다. | -| ADMIN_PORT | `3002` | `number` | Logto Admin Console이 수신하는 로컬 포트입니다. | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Admin Console의 포트를 비활성화하려면 `1` 또는 `true`로 설정하세요. `ADMIN_ENDPOINT`가 설정되지 않은 경우, Admin Console을 완전히 비활성화합니다. | -| DB_URL | N/A | `string` | Logto 데이터베이스를 위한 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)입니다. | -| HTTPS_CERT_PATH | `undefined` | string | undefined | 자세한 내용은 [HTTPS 활성화](#enabling-https)를 참조하세요. | -| HTTPS_KEY_PATH | `undefined` | string | undefined | 동일합니다. | -| TRUST_PROXY_HEADER | `false` | `boolean` | 동일합니다. | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | 온라인 테스트 또는 프로덕션을 위해 사용자 정의 도메인으로 URL을 지정할 수 있습니다. 이는 [OIDC 발급자 식별자](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier)의 값에도 영향을 미칩니다. | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 프로덕션을 위해 사용자 정의 도메인으로 URL을 지정할 수 있습니다 (예: `ADMIN_ENDPOINT=https://admin.domain.com`). 이는 Admin Console 리디렉션 URI의 값에도 영향을 미칩니다. | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | 사용자 이름이 대소문자를 구분하는지 여부를 지정합니다. 이 값을 수정할 때 주의하세요; 변경 사항은 기존 데이터베이스 데이터를 자동으로 조정하지 않으므로 수동 관리가 필요합니다. | +기본값에서 `protocol`은 HTTPS 설정에 따라 `http` 또는 `https`가 됩니다. + +| Key | Default Value | Type | Description | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto가 실행되는 환경의 종류입니다. | +| PORT | `3001` | `number` | Logto가 수신 대기하는 로컬 포트입니다. | +| ADMIN_PORT | `3002` | `number` | Logto 관리 콘솔이 수신 대기하는 로컬 포트입니다. | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 관리 콘솔 포트를 비활성화하려면 `1` 또는 `true`로 설정하세요. `ADMIN_ENDPOINT`가 설정되지 않은 경우, 관리 콘솔이 완전히 비활성화됩니다. | +| DB_URL | N/A | `string` | Logto 데이터베이스용 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)입니다. | +| HTTPS_CERT_PATH | `undefined` | string | undefined | 자세한 내용은 [HTTPS 활성화](#enabling-https)를 참조하세요. | +| HTTPS_KEY_PATH | `undefined` | string | undefined | 위와 동일합니다. | +| TRUST_PROXY_HEADER | `false` | `boolean` | 위와 동일합니다. | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | 온라인 테스트 또는 프로덕션을 위해 커스텀 도메인으로 URL을 지정할 수 있습니다. 이 값은 [OIDC 발급자 식별자](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier)에도 영향을 줍니다. | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 프로덕션 환경에서 커스텀 도메인으로 URL을 지정할 수 있습니다 (예: `ADMIN_ENDPOINT=https://admin.domain.com`). 이 값은 관리 콘솔 리디렉션 URI에도 영향을 줍니다. | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | 사용자 이름의 대소문자 구분 여부를 지정합니다. 이 값을 변경할 때는 주의하세요. 기존 데이터베이스 데이터가 자동으로 조정되지 않으므로 수동으로 관리해야 합니다. | +| SECRET_VAULT_KEK | `undefined` | `string` | [Secret Vault](/secret-vault)에서 데이터 암호화 키 (DEK)를 암호화하는 데 사용되는 키 암호화 키 (KEK)입니다. Secret Vault가 제대로 작동하려면 필수입니다. base64로 인코딩된 문자열이어야 하며, AES-256 (32바이트)을 권장합니다. 예시: `crypto.randomBytes(32).toString('base64')` | ### HTTPS 활성화 {#enabling-https} -#### Node 사용 {#using-node} +#### Node 사용 시 {#using-node} -Node는 HTTPS를 기본적으로 지원합니다. `HTTPS_CERT_PATH`와 `HTTPS_KEY_PATH`를 **모두** 제공하여 Node를 통해 HTTPS를 활성화하세요. +Node는 HTTPS를 기본적으로 지원합니다. Node를 통해 HTTPS를 활성화하려면 **반드시** `HTTPS_CERT_PATH`와 `HTTPS_KEY_PATH`를 모두 제공해야 합니다. -`HTTPS_CERT_PATH`는 HTTPS 인증서의 경로를 의미하며, `HTTPS_KEY_PATH`는 HTTPS 키의 경로를 의미합니다. +`HTTPS_CERT_PATH`는 HTTPS 인증서의 경로를, `HTTPS_KEY_PATH`는 HTTPS 키의 경로를 의미합니다. -#### HTTPS 프록시 사용 {#using-a-https-proxy} +#### HTTPS 프록시 사용 시 {#using-a-https-proxy} -또 다른 일반적인 방법은 Node 앞에 HTTPS 프록시를 두는 것입니다 (예: Nginx). +또 다른 일반적인 방법은 Node 앞에 HTTPS 프록시(Nginx 등)를 두는 것입니다. -이 경우, 프록시 헤더 필드를 신뢰할지 여부를 나타내는 `TRUST_PROXY_HEADER`를 `true`로 설정하고 싶을 것입니다. Logto는 이 값을 [Koa 앱 설정](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings)에 전달합니다. +이 경우, 프록시 헤더 필드를 신뢰할지 여부를 나타내는 `TRUST_PROXY_HEADER`를 `true`로 설정하는 것이 좋습니다. Logto는 이 값을 [Koa 앱 설정](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings)에 전달합니다. -이 필드를 구성해야 할 때는 [TLS 오프로드 프록시 신뢰하기](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies)를 참조하세요. +이 필드를 언제 구성해야 하는지에 대해서는 [TLS 오프로딩 프록시 신뢰하기](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies)를 참조하세요. -## 데이터베이스 구성 {#database-configs} +## 데이터베이스 설정 {#database-configs} -너무 많은 환경 변수를 관리하는 것은 비효율적이고 유연하지 않으므로, 대부분의 일반 구성은 데이터베이스 테이블 `logto_configs`에 저장됩니다. +너무 많은 환경 변수를 관리하는 것은 비효율적이고 유연하지 않으므로, 대부분의 일반 설정은 데이터베이스 테이블 `logto_configs`에 저장됩니다. -이 테이블은 간단한 키-값 저장소이며, 키는 다음과 같이 열거됩니다: +이 테이블은 간단한 키-값 저장소이며, 키는 다음과 같이 열거할 수 있습니다: | Key | Type | Description | | ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | @@ -62,6 +63,6 @@ Node는 HTTPS를 기본적으로 지원합니다. `HTTPS_CERT_PATH`와 `HTTPS_KE ### 지원되는 개인 키 유형 {#supported-private-key-types} -- EC (P-256, secp256k1, P-384, 및 P-521 곡선) +- EC (P-256, secp256k1, P-384, P-521 곡선) - RSA - OKP (Ed25519, Ed448, X25519, X448 하위 유형) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index e2f72be34e6..957fa1ca83d 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -17,7 +17,7 @@ Logto의 [싱글 사인온 (SSO) 솔루션](/end-user-flows/enterprise-sso)은 ## 엔터프라이즈 커넥터 (Enterprise connectors) \{#enterprise-connectors} -Logto는 인기 있는 엔터프라이즈 아이덴티티 제공자(Identity provider)를 위한 사전 구축된 커넥터를 제공하여 빠른 통합이 가능합니다. 맞춤형 요구 사항이 있는 경우, [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) 및 [SAML](https://auth.wiki/saml) 프로토콜을 통한 통합을 지원합니다. +Logto는 인기 있는 엔터프라이즈 아이덴티티 제공자를 위한 사전 구축된 커넥터를 제공하여 빠른 통합을 지원합니다. 맞춤형 요구 사항이 있는 경우, [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) 및 [SAML](https://auth.wiki/saml) 프로토콜을 통한 통합도 지원합니다. ### 인기 엔터프라이즈 커넥터 (Popular enterprise connectors) \{#popular-enterprise-connectors} @@ -81,7 +81,7 @@ Logto는 인기 있는 엔터프라이즈 아이덴티티 제공자(Identity pro ]} /> -표준 커넥터가 귀하의 특정 요구 사항을 충족하지 못하는 경우, 언제든지 저희에게 문의해 주세요. +표준 커넥터가 귀하의 특정 요구 사항을 충족하지 못한다면 언제든지 문의해 주세요. ## 엔터프라이즈 커넥터 설정하기 (Configuring enterprise connectors) \{#configuring-enterprise-connectors} @@ -90,7 +90,7 @@ Logto는 인기 있는 엔터프라이즈 아이덴티티 제공자(Identity pro 3. 고유한 이름을 입력하세요 (예: Acme Company용 Okta). 4. "연결" 탭에서 IdP와의 연결을 구성하세요. 각 커넥터 유형별 가이드를 위에서 확인하세요. 5. "경험" 탭에서 SSO 경험 및 **이메일 도메인**을 맞춤화하세요. -6. SAML 엔터프라이즈 커넥터의 경우, "IdP-initiated SSO" 탭에서 IdP-initiated SSO 활성화는 선택 사항입니다. 자세한 내용은 [가이드](/end-user-flows/enterprise-sso/idp-initiated-sso)를 참고하세요. +6. SAML 엔터프라이즈 커넥터의 경우, "IdP-initiated SSO" 탭에서 IdP-initiated SSO 활성화는 선택 사항입니다. 자세한 내용은 [가이드](/end-user-flows/enterprise-sso/idp-initiated-sso)를 참조하세요. 7. 변경 사항을 저장하세요. 다음 설정에 유의하세요: @@ -98,12 +98,13 @@ Logto는 인기 있는 엔터프라이즈 아이덴티티 제공자(Identity pro - **이메일 도메인**: 사용자가 입력한 이메일의 도메인이 일부 엔터프라이즈 SSO 커넥터의 "엔터프라이즈 이메일 도메인" 필드에 포함되어 있다면, 사용자는 해당 SSO 커넥터의 로그인 URL로 리디렉션됩니다. :::note - SSO 커넥터에서 관련 이메일 도메인을 구성한 후, 해당 도메인에 속한 이메일로 로그인하는 사용자는 반드시 [SSO 로그인](/end-user-flows/enterprise-sso)을 사용해야 한다는 점에 유의하세요. + SSO 커넥터에 관련 이메일 도메인을 설정한 후, 해당 도메인에 속한 이메일로 로그인하는 사용자는 반드시 [SSO 로그인](/end-user-flows/enterprise-sso)을 사용해야 한다는 점에 유의하세요. - 즉, SSO 커넥터에 구성되지 않은 도메인의 이메일만 "이메일 + 인증 코드" 또는 "이메일 + 비밀번호" 로그인(이 두 로그인 방식이 로그인 경험에서 활성화된 경우)을 사용할 수 있습니다. + 즉, SSO 커넥터에 설정되지 않은 도메인의 이메일만 "이메일 + 인증 코드" 또는 "이메일 + 비밀번호" 로그인을 사용할 수 있습니다 (이 두 로그인 방식이 로그인 경험에서 활성화되어 있을 경우). ::: - **사용자 프로필 동기화**: 사용자 프로필 정보(예: 아바타, 이름)를 언제 동기화할지 선택하세요. 기본 동작은 "최초 로그인 시에만 동기화"입니다. "매 로그인 시마다 항상 동기화"도 선택할 수 있지만, 이 경우 사용자 맞춤 데이터가 덮어써질 수 있습니다. +- **토큰 저장 활성화**: OIDC 엔터프라이즈 커넥터의 경우, 사용자가 엔터프라이즈 IdP로 로그인할 때 Logto의 [Secret Vault](/secret-vault)에 액세스 토큰 (Access token) 및 리프레시 토큰 (Refresh token)을 안전하게 저장하도록 토큰 저장을 활성화할 수 있습니다. 이를 통해 사용자가 다시 인증하지 않아도 애플리케이션이 사용자를 대신해 서드파티 API에 접근할 수 있습니다. 자세한 내용은 [Federated token storage](/secret-vault/federated-token-set)를 참고하세요. - **표시 정보**: 선택적으로 커넥터의 표시 이름과 로고를 맞춤화할 수 있습니다. 동일한 이메일 도메인에 여러 커넥터가 연결된 경우 매우 유용합니다. 사용자는 IdP 로그인 페이지로 리디렉션되기 전에 SSO 커넥터 버튼 목록에서 원하는 IdP를 선택하게 됩니다. ## 엔터프라이즈 SSO 활성화 (Enabling enterprise SSO) \{#enabling-enterprise-sso} @@ -112,7 +113,7 @@ Logto는 인기 있는 엔터프라이즈 아이덴티티 제공자(Identity pro 2. "엔터프라이즈 SSO" 토글을 활성화하세요. 3. 변경 사항을 저장하세요. -활성화되면, 로그인 페이지에 "싱글 사인온" 버튼이 표시됩니다. SSO가 활성화된 이메일 도메인을 가진 엔터프라이즈 사용자는 엔터프라이즈 아이덴티티 제공자 (IdP)를 사용해 귀하의 서비스에 접근할 수 있습니다. SSO 사용자 경험에 대해 더 알고 싶다면, 사용자 흐름: [엔터프라이즈 SSO](/end-user-flows/enterprise-sso)를 참고하세요. +활성화되면, 로그인 페이지에 "싱글 사인온 (Single Sign-On)" 버튼이 표시됩니다. SSO가 활성화된 이메일 도메인을 가진 엔터프라이즈 사용자는 엔터프라이즈 아이덴티티 제공자 (IdP)를 사용해 귀하의 서비스에 접근할 수 있습니다. SSO 사용자 경험에 대해 더 알고 싶다면 사용자 흐름: [엔터프라이즈 SSO](/end-user-flows/enterprise-sso)를 참고하세요. ## 조직에 Just-in-Time (JIT) 적용 (Just-in-time to organization) \{#just-in-time-to-organization} @@ -130,7 +131,7 @@ Logto는 조직 내에서 SSO 커넥터 JIT 프로비저닝을 구성할 수 있 - SSO 추가: 이메일이 일치하면 SSO 아이덴티티가 기존 계정에 연결됩니다. -- SSO 제거: 계정에 연결된 SSO 아이덴티티가 제거되지만, 사용자 계정은 유지되며, 사용자는 대체 인증 방법을 설정하라는 안내를 받게 됩니다. +- SSO 제거: 계정에 연결된 SSO 아이덴티티는 삭제되지만, 사용자 계정은 유지되며, 대체 인증 방법 설정을 안내합니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/connectors/social.mdx index fa824efde0c..01f995e8f05 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,15 +7,15 @@ sidebar_position: 3 # 소셜 커넥터 -Logto로 [소셜 로그인](/end-user-flows/sign-up-and-sign-in/social-sign-in)을 활성화하여 사용자 온보딩을 간소화하고 전환율을 높이세요. 사용자는 기존 소셜 미디어 계정을 사용하여 빠르고 안전하게 로그인할 수 있으며, 비밀번호 생성이나 복잡한 등록 절차가 필요하지 않습니다. Logto는 다양한 사전 구축된 소셜 커넥터를 제공하며, 최대한의 유연성을 위해 사용자 정의 통합을 지원합니다. +Logto로 [소셜 로그인](/end-user-flows/sign-up-and-sign-in/social-sign-in)을 활성화하여 사용자 온보딩을 간소화하고 전환율을 높이세요. 사용자는 기존 소셜 미디어 계정을 사용하여 빠르고 안전하게 로그인할 수 있어, 비밀번호 생성이나 복잡한 회원가입 과정을 생략할 수 있습니다. Logto는 다양한 사전 구축된 소셜 커넥터를 제공하며, 최대한의 유연성을 위해 커스텀 통합도 지원합니다. ## 소셜 커넥터 선택하기 \{#choose-your-social-connectors} Logto는 두 가지 유형의 소셜 커넥터를 제공합니다: -### 인기 있는 소셜 커넥터 \{#popular-social-connectors} +### 인기 소셜 커넥터 \{#popular-social-connectors} -Logto는 즉시 사용할 수 있는 인기 있는 소셜 플랫폼에 대한 사전 구성된 커넥터를 제공합니다. +Logto는 즉시 사용할 수 있는 인기 소셜 플랫폼용 사전 구성된 커넥터를 제공합니다. ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'Google 커넥터는 애플리케이션이 Google의 OAuth 2.0 인증 시스템을 사용할 수 있는 간결한 방법을 제공합니다.', + description: 'Google 커넥터는 애플리케이션이 Google의 OAuth 2.0 인증 (Authentication) 시스템을 간결하게 사용할 수 있도록 합니다.', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'Facebook 커넥터는 애플리케이션이 Facebook의 OAuth 2.0 인증 시스템을 사용할 수 있도록 합니다.', + description: 'Facebook 커넥터를 통해 애플리케이션이 Facebook의 OAuth 2.0 인증 (Authentication) 시스템을 사용할 수 있습니다.', customProps: { icon: , } @@ -52,7 +52,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Apple', href: '/integrations/apple', - description: 'Apple 소셜 로그인을 위한 공식 Logto 커넥터입니다.', + description: 'Apple 소셜 로그인용 공식 Logto 커넥터입니다.', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'Microsoft Azure AD 커넥터는 애플리케이션이 Azure의 OAuth 2.0 인증 시스템을 사용할 수 있는 간결한 방법을 제공합니다.', + description: 'Microsoft Azure AD 커넥터는 애플리케이션이 Azure의 OAuth 2.0 인증 (Authentication) 시스템을 간결하게 사용할 수 있도록 합니다.', customProps: { icon: , } @@ -70,7 +70,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'GitHub', href: '/integrations/github', - description: 'GitHub 소셜 로그인을 위한 공식 Logto 커넥터입니다.', + description: 'GitHub 소셜 로그인용 공식 Logto 커넥터입니다.', customProps: { icon: , } @@ -79,7 +79,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Discord', href: '/integrations/discord', - description: 'Discord 커넥터는 애플리케이션이 Discord를 인가 시스템으로 사용할 수 있는 방법을 제공합니다.', + description: 'Discord 커넥터를 통해 애플리케이션이 Discord를 인가 (Authorization) 시스템으로 사용할 수 있습니다.', customProps: { icon: , } @@ -88,11 +88,11 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -[더 보기](/integrations)... +[더 많은 커넥터 보기](/integrations)... -### 소셜 커넥터 사용자 정의하기 \{#customize-your-social-connectors} +### 소셜 커넥터 커스터마이즈하기 \{#customize-your-social-connectors} -사용자 정의 요구 사항에 맞춰 OAuth 2.0 및 OIDC (OpenID Connect) 표준을 활용하여 선호하는 제공자를 통합하세요. +커스텀 요구 사항이 있는 경우, OAuth 2.0 및 OIDC (OpenID Connect) 표준을 활용하여 원하는 공급자를 통합할 수 있습니다. ```mdx-code-block , } @@ -110,7 +110,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'OIDC', href: '/integrations/oidc', - description: 'OAuth 2.0 프로토콜을 위한 공식 Logto 커넥터입니다.', + description: 'OAuth 2.0 프로토콜용 공식 Logto 커넥터입니다.', customProps: { icon: , } @@ -119,32 +119,33 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -표준 커넥터가 특정 요구 사항을 충족하지 못하는 경우, [문의하세요](https://logto.productlane.com/roadmap). Logto OSS 사용자는 긴급한 경우 [커넥터 구현 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector)를 할 수 있습니다. 우리는 항상 [기여](/logto-oss/contribution)를 환영합니다; 여러분의 노력이 동일한 필요를 가진 다른 커뮤니티 구성원에게 큰 도움이 될 수 있습니다. +표준 커넥터가 특정 요구 사항을 충족하지 못하는 경우, 언제든지 [문의해 주세요](https://logto.productlane.com/roadmap). OSS 사용자의 경우, 요구 사항이 긴급하다면 [커넥터 직접 구현하기 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector)가 가능합니다. 우리는 항상 [기여](/logto-oss/contribution)를 환영합니다. 여러분의 노력이 동일한 필요를 가진 다른 커뮤니티 구성원에게 큰 도움이 될 수 있습니다. -## 구성 단계 \{#configuration-steps} +## 설정 단계 \{#configuration-steps} -1. 콘솔 > 커넥터 > 소셜 커넥터로 이동합니다. -2. "소셜 커넥터 추가"를 클릭하고 원하는 유형을 선택합니다. -3. README 가이드를 따라 필수 필드를 완료하고 설정을 사용자 정의합니다. -4. "저장 및 완료"를 클릭하여 마칩니다. -5. 소셜 로그인을 시작하여 커넥터를 테스트합니다. +1. 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요. +2. "소셜 커넥터 추가"를 클릭하고 원하는 유형을 선택하세요. +3. README 가이드를 참고하여 필수 항목을 입력하고 설정을 커스터마이즈하세요. +4. "저장 및 완료"를 클릭하여 마무리하세요. +5. 소셜 로그인을 시작하여 커넥터를 테스트하세요. -다음 설정을 참고하세요: +다음 설정에 유의하세요: -- **아이덴티티 제공자 이름**: 각 소셜 커넥터는 사용자 아이덴티티를 구분하기 위한 고유한 아이덴티티 제공자 (IdP) 이름을 가집니다. 일반 커넥터는 고정된 IdP 이름을 사용하지만, 사용자 정의 커넥터는 고유한 값을 필요로 합니다. 자세한 내용은 [IdP 이름](/connectors/connector-data-structure#target-identity-provider-name)을 참조하세요. -- **사용자 프로필 동기화**: [사용자 프로필 정보](/user-management/user-data#social-identities) (예: 아바타, 사용자 이름)를 언제 동기화할지 선택하세요. 기본값은 "등록 시에만 동기화"입니다. "각 로그인 시 동기화"는 대안이지만 사용자 정의 데이터를 덮어쓸 수 있습니다. +- **아이덴티티 제공자 (IdP) 이름**: 각 소셜 커넥터는 사용자 아이덴티티를 구분하기 위한 고유한 아이덴티티 제공자 (IdP) 이름을 가집니다. 일반 커넥터는 고정된 IdP 이름을 사용하지만, 커스텀 커넥터는 고유한 값을 입력해야 합니다. 자세한 내용은 [IdP 이름](/connectors/connector-data-structure#target-identity-provider-name)을 참고하세요. +- **사용자 프로필 동기화**: [사용자 프로필 정보](/user-management/user-data#social-identities)(예: 아바타, 사용자명)를 언제 동기화할지 선택하세요. 기본값은 "가입 시에만 동기화"입니다. "매 로그인 시 동기화"도 선택할 수 있지만, 이 경우 커스텀 사용자 데이터가 덮어써질 수 있습니다. +- **토큰 저장 활성화**: 지원되는 소셜 커넥터의 경우, 사용자가 소셜 공급자로 로그인할 때 Logto의 [Secret Vault](/secret-vault)에 액세스 토큰 (Access token) 및 리프레시 토큰 (Refresh token)을 안전하게 저장할 수 있습니다. 이를 통해 애플리케이션은 사용자가 다시 인증 (Authentication)하지 않아도 사용자를 대신하여 서드파티 API에 접근할 수 있습니다. 자세한 내용은 [연합 토큰 저장소](/secret-vault/federated-token-set)를 참고하세요. ## 소셜 로그인 활성화하기 \{#enable-social-sign-in} -소셜 커넥터를 성공적으로 생성한 후, 로그인 경험에서 소셜 로그인 버튼 (예: Google로 계속하기)으로 활성화할 수 있습니다. +소셜 커넥터를 성공적으로 생성하면, 로그인 경험(Sign-in Experience)에서 소셜 로그인 버튼(예: Google로 계속하기)으로 활성화할 수 있습니다. 1. - 콘솔 > 로그인 경험 > 가입 및 로그인 + 콘솔 > 로그인 경험 > 회원가입 및 로그인 - 으로 이동합니다. -2. (선택 사항) 소셜 로그인만 필요한 경우 가입 식별자에 "해당 없음"을 선택합니다. -3. 구성된 소셜 커넥터를 "소셜 로그인" 섹션에 추가합니다. -4. 필요에 따라 커넥터의 순서를 조정합니다. -5. "변경 사항 저장"을 클릭하고 "라이브 미리보기"를 테스트합니다. + 으로 이동하세요. +2. (선택 사항) 소셜 로그인만 필요하다면 회원가입 식별자에서 "해당 없음"을 선택하세요. +3. 구성한 소셜 커넥터를 "소셜 로그인" 섹션에 추가하세요. +4. 필요에 따라 커넥터의 순서를 조정하세요. +5. "변경사항 저장"을 클릭하고 "라이브 미리보기"로 테스트하세요. -자세한 내용은 [소셜 로그인](/end-user-flows/sign-up-and-sign-in/social-sign-in)을 참조하세요. +자세한 내용은 [소셜 로그인](/end-user-flows/sign-up-and-sign-in/social-sign-in)을 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index 7102113ea45..0641aec2f8f 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -10,20 +10,65 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Facebook 소셜 로그인을 설정하세요 +# Facebook 소셜 로그인을 설정하세요 (Set up social login with Facebook) -Facebook 소셜 로그인에 대한 공식 Logto 커넥터입니다. +Facebook OAuth 2.0 인증 (Authentication) 시스템을 통합하여 Facebook으로 로그인, 계정 연동, Facebook API에 대한 안전한 접근을 활성화하세요. -## 시작하기 \{#get-started} +## 시작하기 (Get started) \{#get-started} -Facebook 커넥터는 애플리케이션이 Facebook의 OAuth 2.0 인증 시스템을 사용할 수 있는 간결한 방법을 제공합니다. +Facebook 커넥터 (Connector)는 OAuth 2.0 통합을 가능하게 하여 애플리케이션에서 다음을 할 수 있습니다: + +- “Facebook으로 로그인” 인증 (Authentication) 추가 +- 사용자 계정을 Facebook 아이덴티티에 연동 +- Facebook에서 사용자 프로필 정보 동기화 +- Logto Secret Vault에 안전하게 저장된 토큰을 통해 Facebook API에 접근하여 자동화 작업 수행 (예: 스레드에 답변; 앱에서 콘텐츠 및 동영상 게시) + +이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 Facebook 커넥터 (Connector)를 생성하세요: + +1. [Logto > 커넥터 (Connector) > 소셜 커넥터 (Social connector)](https://cloud.logto.io/to/connectors/social)로 이동하세요. +2. **소셜 커넥터 추가**를 클릭하고, **Facebook**을 선택한 후 **다음**을 클릭하여 단계별 튜토리얼을 따라 통합을 완료하세요. -## 참고 자료 \{#references} +## Facebook 커넥터 (Connector) 활용하기 \{#utilize-the-facebook-connector} + +Facebook 커넥터 (Connector)를 생성하고 Facebook과 연결한 후, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요: + +### "Facebook으로 로그인" 활성화 \{#enable-sign-in-with-facebook} + +1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요. +2. **소셜 로그인** 섹션에서 Facebook 커넥터 (Connector)를 추가하여 사용자가 Facebook으로 인증 (Authentication)할 수 있도록 하세요. + +[소셜 로그인 경험](/end-user-flows/sign-up-and-sign-in/social-sign-in)에 대해 더 알아보세요. + +### Facebook 계정 연동 또는 연결 해제 \{#link-or-unlink-a-facebook-account} + +Account API를 사용하여 앱 내에 맞춤형 계정 센터를 구축하고, 로그인한 사용자가 자신의 Facebook 계정을 연동하거나 연결 해제할 수 있도록 하세요. [Account API 튜토리얼을 따라하세요](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Facebook 커넥터 (Connector)는 소셜 로그인을 활성화하지 않고 계정 연동 및 API 접근만을 위해 활성화할 수도 있습니다. +::: + +### Facebook API 접근 및 작업 수행 \{#access-facebook-api-and-perform-actions} + +애플리케이션은 Secret Vault에서 저장된 Facebook 액세스 토큰 (Access token)을 가져와 Facebook API를 호출하고 백엔드 작업을 자동화할 수 있습니다 (예: 콘텐츠 게시 또는 게시물 관리). API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요. + +## 사용자의 Facebook 아이덴티티 관리 \{#manage-user-s-facebook-identity} + +사용자가 Facebook 계정을 연동한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다: + +1. 사용자 관리로 이동하여 사용자의 프로필을 엽니다. +2. **소셜 연결** 항목에서 Facebook 항목을 찾아 **관리**를 클릭하세요. +3. 이 페이지에서 관리자는 사용자의 Facebook 연결을 관리하고, Facebook 계정에서 제공 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 (Access token) 상태를 확인할 수 있습니다. + +:::note +Facebook의 액세스 토큰 (Access token) 응답에는 구체적인 스코프 (Scope) 정보가 포함되어 있지 않으므로, Logto는 사용자가 부여한 권한 (Permission) 목록을 직접 표시할 수 없습니다. 그러나 사용자가 인가 (Authorization) 과정에서 요청된 스코프 (Scope)에 동의했다면, 애플리케이션은 Facebook API에 접근할 때 해당 권한 (Permission)을 갖게 됩니다. 필요한 스코프 (Scope)를 Facebook 개발자 콘솔과 Logto 모두에 정확히 설정하여 앱이 필요한 접근 권한을 갖도록 하는 것이 좋습니다. +::: + +## 참고 자료 (Reference) \{#reference} + +Facebook for Developers - Documentation -- [Facebook 로그인 - 문서 - Facebook for Developers](https://developers.facebook.com/docs/facebook-login/) - - [로그인 흐름 수동으로 구축하기](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [권한 가이드](https://developers.facebook.com/docs/facebook-login/guides/permissions) +Facebook Login Documentation diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index acbb0f9d4aa..541679407a8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,54 +1,100 @@ -### Facebook 개발자 계정 등록 \{#register-a-facebook-developer-account} +## 1단계: Facebook App Dashboard에서 앱 설정하기 \{#step-1-set-up-an-app-on-facebook-app-dashboard} -[Facebook 개발자로 등록](https://developers.facebook.com/docs/development/register/)하세요. 아직 계정이 없다면 등록하세요. +Facebook을 인증 (Authentication) 제공자로 사용하기 전에, Facebook 개발자 플랫폼에서 앱을 설정하여 OAuth 2.0 자격 증명을 받아야 합니다. -### Facebook 앱 설정 \{#set-up-a-facebook-app} +1. 아직 계정이 없다면 [Facebook 개발자 등록](https://developers.facebook.com/docs/development/register/)을 하세요. +2. [앱](https://developers.facebook.com/apps) 페이지로 이동하세요. +3. 기존 앱을 클릭하거나 필요하다면 [새 앱을 생성](https://developers.facebook.com/docs/development/create-an-app)하세요. -1. [앱](https://developers.facebook.com/apps) 페이지를 방문하세요. -2. 기존 앱을 클릭하거나 필요하다면 [새로 생성](https://developers.facebook.com/docs/development/create-an-app)하세요. - - 선택한 [앱 유형](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types)은 자유롭게 선택할 수 있지만, _Facebook 로그인_ 제품이 포함되어야 합니다. -3. 앱 대시보드 페이지에서 "제품 추가" 섹션으로 스크롤하여 "Facebook 로그인" 카드의 "설정" 버튼을 클릭하세요. -4. Facebook 로그인 빠른 시작 페이지를 건너뛰고, 사이드바 -> "제품" -> "Facebook 로그인" -> "설정"을 클릭하세요. -5. Facebook 로그인 설정 페이지에서 "유효한 OAuth 리디렉션 URI" 필드에 `${your_logto_origin}/callback/${connector_id}`를 입력하세요. `connector_id`는 Logto 관리자 콘솔 커넥터 세부 정보 페이지의 상단 바에서 찾을 수 있습니다. 예를 들어: - - 프로덕션의 경우 `https://logto.dev/callback/${connector_id}` - - 로컬 환경에서 테스트할 경우 `https://localhost:3001/callback/${connector_id}` -6. 오른쪽 하단 모서리의 "변경 사항 저장" 버튼을 클릭하세요. +:::tip +사용 사례(Use case)는 앱이 Meta와 상호작용하는 주요 방식이며, 앱에서 사용할 수 있는 API, 기능, 권한, 제품을 결정합니다. 소셜 인증 (Authentication)만 필요하다면(이메일 및 public_profile 획득), "Authentication and request data from users with Facebook Login"을 선택하세요. Facebook API에 접근하려면 원하는 사용 사례를 선택하세요. 대부분의 경우 앱 생성 후 "Facebook Login for business" 통합도 지원합니다. +::: -## 커넥터 JSON 작성 \{#compose-the-connector-json} +4. 앱 생성 후, 앱 대시보드 페이지에서 **Use cases > Facebook Login > Settings** 또는 **Facebook Login for business > Settings**로 이동하세요. +5. **Valid OAuth Redirect URIs**에 Logto **Callback URI**를 입력하세요(Logto Facebook 커넥터에서 복사). 사용자가 Facebook으로 로그인하면, 이곳으로 리디렉션되어 Logto가 인증 (Authentication)을 완료하는 데 필요한 인가 코드가 전달됩니다. +6. **Use cases**로 이동하여 사용 사례의 **Customize**를 클릭해 스코프를 추가하세요. Logto에서 Facebook 로그인을 구현하려면 `email`과 `public_profile` 추가를 권장합니다. -1. Facebook 앱 대시보드 페이지에서 사이드바 -> "설정" -> "기본"을 클릭하세요. -2. 패널에서 "앱 ID"와 "앱 비밀"을 볼 수 있습니다. -3. 앱 비밀 입력 상자 옆의 "보기" 버튼을 클릭하여 내용을 복사하세요. -4. Logto 커넥터 설정을 작성하세요: - - *App ID*에서 가져온 문자열로 `clientId` 필드를 작성하세요. - - *App secret*에서 가져온 문자열로 `clientSecret` 필드를 작성하세요. - - [권한](https://developers.facebook.com/docs/permissions/reference)의 쉼표 또는 공백으로 구분된 목록으로 `scope` 필드를 문자열로 작성하세요. 스코프를 지정하지 않으면 기본 스코프는 `email,public_profile`입니다. +## 2단계: 클라이언트 자격 증명으로 Logto 커넥터 설정 \{#step-2-set-up-logto-connector-with-client-credentials} -## Facebook 테스트 사용자로 로그인 테스트 \{#test-sign-in-with-facebooks-test-users} +1. Facebook App Dashboard에서 사이드바의 **App settings > Basic**을 클릭하세요. +2. 패널에서 **App ID**와 **App secret**을 확인할 수 있습니다. +3. App secret 입력란 옆의 **Show** 버튼을 클릭해 내용을 표시하고 복사하세요. +4. Logto Facebook 커넥터 설정을 구성하세요: + - `clientId` 필드에 **App ID**를 입력하세요. + - `clientSecret` 필드에 **App secret**을 입력하세요. + - Logto에서 **Save and Done**을 클릭해 아이덴티티 시스템을 Facebook과 연결하세요. -테스트, 개발자, 관리자 사용자의 계정을 사용하여 개발 및 라이브 [앱 모드](https://developers.facebook.com/docs/development/build-and-test/app-modes)에서 관련 앱으로 로그인 테스트를 할 수 있습니다. +## 3단계: 스코프 구성 \{#step-3-configure-scopes} -또한 [앱을 라이브로 전환](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)하여 모든 Facebook 사용자가 앱으로 로그인할 수 있도록 할 수 있습니다. +스코프는 앱이 사용자에게 요청하는 권한을 정의하며, 사용자의 Facebook 계정에서 프로젝트가 접근할 수 있는 개인 데이터 범위를 제어합니다. -- 앱 대시보드 페이지에서 사이드바 -> "역할" -> "테스트 사용자"를 클릭하세요. -- "테스트 사용자 생성" 버튼을 클릭하여 테스트 사용자를 생성하세요. -- 기존 테스트 사용자의 "옵션" 버튼을 클릭하면 "이름 및 비밀번호 변경" 등 더 많은 작업을 볼 수 있습니다. +### Facebook App Dashboard에서 스코프 구성 \{#configure-scopes-in-facebook-app-dashboard} -## Facebook 로그인 설정 게시 \{#publish-facebook-sign-in-settings} +1. **Facebook App Dashboard > Use cases**로 이동하여 **Customize** 버튼을 클릭하세요. +2. 앱에 필요한 스코프만 추가하세요. 사용자는 Facebook 동의 화면에서 이 권한을 검토하고 승인합니다: + - **인증 (Authentication)용(필수)**: `email` 및 `public_profile` + - **API 접근용(선택)**: 앱에 필요한 추가 스코프(예: Threads API 접근을 위한 `threads_content_publish`, `threads_read_replies`). 사용 가능한 서비스는 [Meta 개발자 문서](https://developers.facebook.com/docs/)를 참고하세요. -일반적으로 테스트, 관리자, 개발자 사용자만 [개발 모드](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode)에서 관련 앱으로 로그인할 수 있습니다. +### Logto에서 스코프 구성 \{#configure-scopes-in-logto} -프로덕션 환경에서 일반 Facebook 사용자가 앱으로 로그인할 수 있도록 하려면, 앱 유형에 따라 Facebook 앱을 *[라이브 모드](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)*로 전환해야 할 수도 있습니다. 예를 들어, 순수 _비즈니스 유형_ 앱은 "라이브" 전환 버튼이 없지만 사용을 차단하지는 않습니다. +필요에 따라 다음 방법 중 하나 이상을 선택하세요: -1. Facebook 앱 대시보드 페이지에서 사이드바 -> "설정" -> "기본"을 클릭하세요. -2. 필요하다면 패널에서 "개인정보 보호 정책 URL" 및 "사용자 데이터 삭제" 필드를 작성하세요. -3. 오른쪽 하단 모서리의 "변경 사항 저장" 버튼을 클릭하세요. -4. 앱 상단 바의 "라이브" 전환 버튼을 클릭하세요. +**옵션 1: 추가 API 스코프가 필요 없는 경우** -## 구성 유형 \{#config-types} +- Logto Facebook 커넥터의 `Scopes` 필드를 비워 두세요. +- 기본 스코프 `email public_profile`이 요청되어 Logto가 기본 사용자 정보를 올바르게 가져올 수 있습니다. -| 이름 | 유형 | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**옵션 2: 로그인 시 추가 스코프 요청** + +- 원하는 모든 스코프를 **Scopes** 필드에 공백으로 구분하여 입력하세요. +- 여기에 입력한 스코프가 기본값을 덮어쓰므로, 항상 인증 (Authentication) 스코프인 `email public_profile`을 포함하세요. + +**옵션 3: 나중에 점진적으로 스코프 요청** + +- 사용자가 로그인한 후, 페더레이티드 소셜 인가 (Authorization) 플로우를 다시 시작하고 사용자의 저장된 토큰 세트를 업데이트하여 추가 스코프를 요청할 수 있습니다. +- 이러한 추가 스코프는 Logto Facebook 커넥터의 `Scopes` 필드에 입력할 필요가 없으며, Logto의 Social Verification API를 통해 달성할 수 있습니다. + +이 과정을 따르면, Logto Facebook 커넥터는 앱에 꼭 필요한 권한만 요청합니다. + +:::tip +앱이 Facebook API에 접근하여 작업을 수행하려면, Logto Facebook 커넥터에서 **Store tokens for persistent API access**를 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요. +::: + +## 4단계: 일반 설정 \{#step-4-general-settings} + +아래는 Facebook과의 연결을 막지는 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다. + +### 프로필 정보 동기화 \{#sync-profile-information} + +Facebook 커넥터에서 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 선택지는 다음과 같습니다: + +- **가입 시에만 동기화**: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다. +- **로그인 시마다 항상 동기화**: 사용자가 로그인할 때마다 프로필 정보를 업데이트합니다. + +### Facebook API 접근을 위한 토큰 저장(선택 사항) \{#store-tokens-to-access-facebook-apis-optional} + +Facebook API에 접근하여 사용자 인가 (Authorization)로 작업을 수행하려면(소셜 로그인 또는 계정 연동을 통해), Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다. + +1. 위 튜토리얼을 따라 필요한 스코프를 추가하세요. +2. Logto Facebook 커넥터에서 **Store tokens for persistent API access**를 활성화하세요. Logto는 Facebook 액세스 토큰을 Secret Vault에 안전하게 저장합니다. + +:::note +Facebook은 리프레시 토큰을 제공하지 않습니다. 하지만 토큰 저장이 활성화되면, Logto는 사용자 인증 (Authentication) 시 자동으로 장기 액세스 토큰(60일)을 요청합니다. 이 기간 동안 사용자는 수동으로 액세스 토큰을 철회할 수 있지만, 그렇지 않으면 Facebook API 접근을 위해 재인가가 필요하지 않습니다. 참고: `offline_access`를 `Scope` 필드에 추가하지 마세요. 오류가 발생할 수 있습니다. +::: + +## 5단계: Facebook 테스트 사용자로 로그인 테스트(선택 사항) \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +테스트, 개발자, 관리자 사용자 계정으로 앱 로그인 테스트를 할 수 있습니다. 앱을 바로 게시하여 모든 Facebook 사용자가 로그인할 수 있도록 할 수도 있습니다. + +1. Facebook App Dashboard에서 사이드바의 **App roles > Test Users**를 클릭하세요. +2. **Create test users** 버튼을 클릭해 테스트 사용자를 생성하세요. +3. 기존 테스트 사용자의 **Options** 버튼을 클릭하면 "이름 및 비밀번호 변경" 등 추가 작업을 할 수 있습니다. + +## 6단계: Facebook 로그인 설정 게시 \{#step-6-publish-facebook-sign-in-settings} + +일반적으로 테스트, 관리자, 개발자 사용자만 앱으로 로그인할 수 있습니다. 실제 환경에서 일반 Facebook 사용자가 앱으로 로그인할 수 있도록 하려면 앱을 게시해야 할 수 있습니다. + +1. Facebook App Dashboard에서 사이드바의 **Publish**를 클릭하세요. +2. 필요하다면 **Privacy Policy URL** 및 **User data deletion** 필드를 입력하세요. +3. 오른쪽 하단의 **Save changes** 버튼을 클릭하세요. +4. 앱 상단 바의 **Live** 스위치 버튼을 클릭하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index a9f5119842d..0c346aaa160 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -3,8 +3,8 @@ slug: /integrations/github sidebar_label: GitHub sidebar_custom_props: darkLogoFilename: 'github-dark.svg' - description: GitHub은 소프트웨어 개발 및 버전 관리를 위한 온라인 커뮤니티입니다. -tutorial_config_name: GitHub OAuth 앱 + description: GitHub는 소프트웨어 개발 및 버전 관리를 위한 온라인 커뮤니티입니다. +tutorial_config_name: GitHub OAuth app --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -13,26 +13,71 @@ import Integration from './_integration.mdx'; # GitHub 소셜 로그인을 설정하세요 -GitHub 소셜 로그인에 대한 공식 Logto 커넥터입니다. +GitHub OAuth 앱을 통합하여 GitHub로 로그인, 계정 연결, 그리고 GitHub API에 대한 안전한 접근을 활성화하세요. ## 시작하기 \{#get-started} -GitHub 커넥터는 최종 사용자가 GitHub OAuth 2.0 인증 프로토콜을 통해 자신의 GitHub 계정을 사용하여 애플리케이션에 로그인할 수 있도록 합니다. +GitHub 커넥터는 OAuth 2.0 통합을 지원하여 애플리케이션에서 다음을 할 수 있습니다: + +- "GitHub로 로그인" 인증 (Authentication) 추가 +- 사용자 계정을 GitHub 아이덴티티에 연결 +- GitHub에서 사용자 프로필 정보 동기화 +- Logto Secret Vault에 안전하게 저장된 토큰을 통해 GitHub API에 접근하여 자동화 작업 수행 (예: GitHub 이슈 생성, 애플리케이션에서 저장소 관리 등) + +이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 GitHub 커넥터를 생성하세요: + +1. Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요. +2. **소셜 커넥터 추가**를 클릭하고, **GitHub**를 선택한 후 **다음**을 클릭하여 단계별 튜토리얼을 따라 통합을 완료하세요. -## GitHub 커넥터 테스트 \{#test-github-connector} +## GitHub 커넥터 활용하기 \{#utilize-the-github-connector} + +GitHub 커넥터를 생성하고 GitHub와 연결한 후, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요: + +### "GitHub로 로그인" 활성화 \{#enable-sign-in-with-github} + +1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요. +2. **소셜 로그인** 섹션에서 GitHub 커넥터를 추가하여 사용자가 GitHub로 인증 (Authentication)할 수 있도록 하세요. + +[소셜 로그인 경험](/end-user-flows/sign-up-and-sign-in/social-sign-in)에 대해 자세히 알아보세요. + +### GitHub 계정 연결 또는 연결 해제 \{#link-or-unlink-a-github-account} + +Account API를 사용하여 애플리케이션 내에 맞춤형 계정 센터를 구축하고, 로그인한 사용자가 자신의 GitHub 계정을 연결하거나 연결 해제할 수 있도록 하세요. [Account API 튜토리얼을 따라하세요](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -이제 완료되었습니다. GitHub 커넥터가 이제 사용 가능해야 합니다. [로그인 경험에서 소셜 커넥터 활성화](/connectors/social-connectors/#enable-social-sign-in)를 잊지 마세요. +:::tip +GitHub 커넥터를 소셜 로그인 용도로 활성화하지 않고, 계정 연결 및 API 접근 용도로만 활성화하는 것도 가능합니다. +::: + +### GitHub API 접근 및 작업 수행 \{#access-github-apis-and-perform-actions} + +애플리케이션은 Secret Vault에서 저장된 GitHub 액세스 토큰을 가져와 GitHub API를 호출하고 백엔드 작업을 자동화할 수 있습니다 (예: 이슈 생성, 저장소 관리, 워크플로우 자동화 등). API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요. + +## 사용자의 GitHub 아이덴티티 관리 \{#manage-user-s-github-identity} + +사용자가 자신의 GitHub 계정을 연결한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다: + +1. Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다. +2. **소셜 연결** 항목에서 GitHub 항목을 찾아 **관리**를 클릭하세요. +3. 이 페이지에서 관리자는 사용자의 GitHub 연결을 관리하고, GitHub 계정에서 동의 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 상태를 점검할 수 있습니다. + +:::note +GitHub의 액세스 토큰 응답에는 구체적인 스코프 정보가 포함되어 있지 않으므로, Logto는 사용자가 부여한 권한 (Permissions) 목록을 직접 표시할 수 없습니다. 그러나 사용자가 인가 (Authorization) 과정에서 요청된 스코프에 동의했다면, 애플리케이션은 GitHub API에 접근할 때 해당 권한 (Permissions)을 갖게 됩니다. +::: ## 참고 자료 \{#reference} - GitHub - 개발자 - 앱 + GitHub 개발자 문서 - 앱 소개 - GitHub - 개발자 - 앱 - OAuth 앱 생성 + GitHub 개발자 문서 - OAuth 앱 생성 + + + + GitHub OAuth 앱 스코프 문서 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index 85824193f82..427b567be0f 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,35 +1,99 @@ -### GitHub 계정으로 로그인하기 \{#sign-in-with-github-account} +## 1단계: GitHub에서 OAuth 앱 생성하기 \{#step-1-create-an-oauth-app-on-github} -[GitHub 웹사이트](https://github.com/)로 이동하여 GitHub 계정으로 로그인하세요. 계정이 없다면 새로 등록할 수 있습니다. +GitHub를 인증 (Authentication) 제공자로 사용하려면, 먼저 GitHub에서 OAuth 앱을 생성하여 OAuth 2.0 자격 증명을 받아야 합니다. -### OAuth 앱 생성 및 구성하기 \{#create-and-configure-oauth-app} +1. [GitHub](https://github.com/)에 접속하여 계정으로 로그인하거나, 필요하다면 새 계정을 만드세요. +2. [Settings > Developer settings > OAuth apps](https://github.com/settings/developers)로 이동하세요. +3. **New OAuth App**을 클릭하여 새 애플리케이션을 등록하세요: + - **Application name**: 앱의 설명이 잘 드러나는 이름을 입력하세요. + - **Homepage URL**: 애플리케이션의 홈페이지 URL을 입력하세요. + - **Authorization callback URL**: Logto GitHub 커넥터에서 **Callback URI**를 복사하여 여기에 붙여넣으세요. 사용자가 GitHub로 로그인하면, 인가 (Authorization) 코드와 함께 이곳으로 리디렉션되며, Logto가 인증 (Authentication)을 완료하는 데 사용합니다. + - **Application description**: (선택 사항) 앱에 대한 간단한 설명을 추가하세요. +4. **Register application**을 클릭하여 OAuth 앱을 생성하세요. -[OAuth 앱 생성](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) 가이드를 따라 새 애플리케이션을 등록하세요. +:::note +**Enable Device Flow** 체크박스는 선택하지 않는 것을 권장합니다. GitHub 모바일 기기에서 로그인하는 사용자는 GitHub 모바일 앱에서 최초 로그인 동작을 확인해야 합니다. 많은 GitHub 사용자가 휴대폰에 GitHub 모바일 앱을 설치하지 않아 로그인 흐름이 차단될 수 있습니다. 최종 사용자가 GitHub 모바일 앱을 통해 로그인 흐름을 확인할 것으로 예상되는 경우에만 활성화하세요. [디바이스 플로우](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)에 대한 자세한 내용을 참고하세요. -**Application name**에 새 OAuth 애플리케이션의 이름을 지정하고 앱의 **Homepage URL**을 입력하세요. **Application description** 필드는 비워둘 수 있으며 **Authorization callback URL**을 `${your_logto_origin}/callback/${connector_id}`로 설정할 수 있습니다. `connector_id`는 Logto Admin Console 커넥터 세부 정보 페이지의 상단 바에서 찾을 수 있습니다. +GitHub OAuth 앱 설정에 대한 자세한 내용은 [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)을 참고하세요. +::: -:::note +## 2단계: Logto 커넥터 구성하기 \{#step-2-configure-your-logto-connector} + +GitHub에서 OAuth 앱을 생성한 후, 상세 페이지로 리디렉션되며 여기서 Client ID를 복사하고 Client secret을 생성할 수 있습니다. + +1. GitHub OAuth 앱에서 **Client ID**를 복사하여 Logto의 `clientId` 필드에 붙여넣으세요. +2. GitHub에서 **Generate a new client secret**을 클릭하여 새 시크릿을 생성한 뒤, 이를 복사하여 Logto의 `clientSecret` 필드에 붙여넣으세요. +3. Logto에서 **Save and Done**을 클릭하여 아이덴티티 시스템을 GitHub와 연결하세요. + +:::warning +Client secret은 안전하게 보관하고, 클라이언트 측 코드에 노출하지 마세요. GitHub client secret은 분실 시 복구할 수 없으므로, 새로 생성해야 합니다. +::: + +## 3단계: 스코프 구성하기 (선택 사항) \{#step-3-configure-scopes-optional} + +스코프 (Scope)는 앱이 사용자로부터 요청하는 권한을 정의하며, 앱이 사용자의 GitHub 계정에서 접근할 수 있는 데이터를 제어합니다. + +Logto의 `Scopes` 필드를 사용하여 GitHub에서 추가 권한을 요청할 수 있습니다. 필요에 따라 다음 중 한 가지 방법을 선택하세요: + +### 옵션 1: 추가 API 스코프가 필요 없는 경우 \{#option-1-no-extra-api-scopes-needed} + +- Logto GitHub 커넥터의 `Scopes` 필드를 비워두세요. +- 기본 스코프인 `read:user`가 요청되어 Logto가 기본 사용자 정보(예: 이메일, 이름, 아바타)를 올바르게 가져올 수 있습니다. -로그인 시 "The redirect_uri MUST match the registered callback URL for this application."라는 오류 메시지가 나타나면, GitHub OAuth 앱과 Logto 앱의 Authorization Callback URL을 (물론 프로토콜을 포함하여) 일치시키면 문제를 해결할 수 있습니다. +### 옵션 2: 로그인 시 추가 스코프 요청 \{#option-2-request-additional-scopes-at-sign-in} +- 모든 [GitHub OAuth 앱용 스코프](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)를 확인하고, 앱에 필요한 스코프만 추가하세요. +- 원하는 모든 스코프를 **Scopes** 필드에 공백으로 구분하여 입력하세요. +- 여기에 입력한 스코프는 기본값을 덮어쓰므로, 항상 인증 (Authentication) 스코프인 `read:user`를 포함해야 합니다. +- 자주 사용되는 추가 스코프 예시: + - `repo`: 비공개 저장소 전체 제어 + - `public_repo`: 공개 저장소 접근 + - `user:email`: 사용자 이메일 주소 접근 + - `notifications`: 알림 접근 +- 모든 스코프가 올바르게 입력되었는지, 유효한지 확인하세요. 잘못되었거나 지원되지 않는 스코프는 GitHub에서 "Invalid scope" 오류를 발생시킵니다. + +### 옵션 3: 나중에 점진적으로 스코프 요청 \{#option-3-request-incremental-scopes-later} + +- 사용자가 로그인한 후, 필요에 따라 연합 소셜 인가 (Authorization) 플로우를 다시 시작하고 사용자의 저장된 토큰 세트를 업데이트하여 추가 스코프를 요청할 수 있습니다. +- 이러한 추가 스코프는 Logto GitHub 커넥터의 `Scopes` 필드에 입력할 필요가 없으며, Logto의 Social Verification API를 통해 달성할 수 있습니다. + +이 과정을 따르면, Logto GitHub 커넥터는 앱에 꼭 필요한 권한만 요청하게 됩니다. + +:::tip +앱이 GitHub API에 접근하여 작업을 수행하기 위해 이러한 스코프를 요청한다면, Logto GitHub 커넥터에서 **Store tokens for persistent API access**를 반드시 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요. ::: -**Enable Device Flow** 앞의 체크박스를 선택하지 않는 것이 좋습니다. 그렇지 않으면 모바일 기기에서 GitHub으로 로그인하는 사용자가 GitHub 앱에서 초기 로그인 동작을 확인해야 합니다. 많은 GitHub 사용자가 휴대폰에 GitHub 모바일 앱을 설치하지 않아서 로그인 흐름이 차단될 수 있습니다. 최종 사용자가 로그인 흐름을 확인하도록 기대하는 경우에는 우리의 제안을 무시하세요. [디바이스 흐름](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)에 대한 자세한 내용을 참조하세요. +## 4단계: 일반 설정 \{#step-4-general-settings} + +다음은 GitHub와의 연결에는 영향을 주지 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다. + +### 프로필 정보 동기화 \{#sync-profile-information} -### OAuth 앱 관리하기 \{#managing-oauth-apps} +GitHub 커넥터에서 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요: -[OAuth Apps 페이지](https://github.com/settings/developers)로 이동하여 기존 OAuth 앱을 추가, 편집 또는 삭제할 수 있습니다. OAuth 앱 세부 정보 페이지에서 `Client ID`를 찾고 `Client secrets`를 생성할 수 있습니다. +- **Only sync at sign-up**: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다. +- **Always sync at sign-in**: 사용자가 로그인할 때마다 프로필 정보를 업데이트합니다. -### 커넥터 구성하기 \{#configure-your-connector} +### GitHub API 접근을 위한 토큰 저장 (선택 사항) \{#store-tokens-to-access-github-apis-optional} + +소셜 로그인 또는 계정 연동을 통해 사용자 인가 (Authorization)로 GitHub API에 접근하고 작업을 수행하려면, Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다. + +1. 위의 안내에 따라 필요한 스코프를 추가하세요. +2. Logto GitHub 커넥터에서 **Store tokens for persistent API access**를 활성화하세요. Logto는 GitHub 액세스 토큰을 Secret Vault에 안전하게 저장합니다. + +:::note +이 튜토리얼에서 설명한 GitHub **OAuth App**을 사용할 때는, GitHub에서 리프레시 토큰 (Refresh token)을 받을 수 없습니다. GitHub의 액세스 토큰 (Access token)은 사용자가 직접 토큰을 취소하지 않는 한 만료되지 않기 때문입니다. 따라서 `Scopes` 필드에 `offline_access`를 추가할 필요가 없으며, 추가할 경우 오류가 발생할 수 있습니다. + +액세스 토큰이 만료되거나 리프레시 토큰을 사용하고 싶다면, **GitHub App**과의 연동을 고려하세요. [GitHub Apps와 OAuth Apps의 차이점](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)을 참고하세요. +::: -이전 섹션에서 언급한 OAuth 앱 세부 정보 페이지에서 얻은 *Client ID*와 *Client Secret*으로 `clientId` 및 `clientSecret` 필드를 채우세요. +## 5단계: 통합 테스트하기 (선택 사항) \{#step-5-test-your-integration-optional} -`scope`는 [스코프](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)의 공백으로 구분된 목록입니다. 제공되지 않으면, 스코프는 기본적으로 `read:user`로 설정됩니다. +실서비스에 적용하기 전에 GitHub 연동을 테스트하세요: -### 구성 유형 \{#config-types} +1. Logto 개발 테넌트에서 커넥터를 사용하세요. +2. 사용자가 GitHub로 로그인할 수 있는지 확인하세요. +3. 올바른 스코프가 요청되는지 확인하세요. +4. 토큰을 저장하는 경우 API 호출도 테스트하세요. -| 이름 | 유형 | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +GitHub OAuth 앱은 모든 GitHub 사용자 계정과 즉시 작동하므로, 다른 플랫폼처럼 테스트 사용자나 앱 승인 절차가 필요하지 않습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index f7d8a04d34a..955a0cc4218 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -12,14 +12,66 @@ import Integration from './_integration.mdx'; # Google 소셜 로그인을 설정하세요 -Google 커넥터는 애플리케이션이 Google의 OAuth 2.0 인증 시스템을 사용할 수 있는 간결한 방법을 제공합니다. +Google OAuth 2.0 인증 시스템을 통합하여 Google로 로그인, 계정 연결, Google API에 대한 안전한 접근을 활성화하세요. +## 시작하기 \{#get-started} + +Google 커넥터는 OAuth 2.0 통합을 가능하게 하여 애플리케이션에서 다음을 할 수 있습니다: + +- "Google로 로그인" 인증 추가 +- 사용자 계정을 Google 아이덴티티에 연결 +- Google에서 사용자 프로필 정보 동기화 +- Logto Secret Vault에 안전하게 저장된 토큰을 통해 Google API에 접근하여 자동화 작업 수행 (예: Google Docs 편집, 앱 내에서 Calendar 이벤트 관리 등) + +이러한 인증 기능을 설정하려면 먼저 Logto에서 Google 커넥터를 생성하세요: + +1. Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요. +2. **소셜 커넥터 추가**를 클릭하고, **Google**을 선택한 후 **다음**을 클릭하여 단계별 튜토리얼을 따라 통합을 완료하세요. + -## 참고 자료 \{#references} +## Google 커넥터 활용하기 \{#utilize-the-google-connector} + +Google 커넥터를 생성하고 Google과 연결한 후, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요: + +### "Google로 로그인" 활성화 \{#enable-sign-in-with-google} + +1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요. +2. **소셜 로그인** 섹션에서 Google 커넥터를 추가하여 사용자가 Google로 인증할 수 있도록 하세요. +3. 선택적으로, 로그인 및 회원가입 페이지에서 **Google One Tap**을 활성화하여 간편한 인증 경험을 제공할 수 있습니다. + +[소셜 로그인 경험](/end-user-flows/sign-up-and-sign-in/social-sign-in)에 대해 자세히 알아보세요. + +### Google 계정 연결 또는 연결 해제 \{#link-or-unlink-a-google-account} + +Account API를 사용하여 앱 내에 맞춤형 계정 센터를 구축하고, 로그인한 사용자가 Google 계정을 연결하거나 연결 해제할 수 있도록 하세요. [Account API 튜토리얼을 따라하세요](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +Google 커넥터를 소셜 로그인 없이 계정 연결 및 API 접근 용도로만 활성화하는 것도 가능합니다. +::: + +### Google API 접근 및 작업 수행 \{#access-google-apis-and-perform-actions} + +애플리케이션은 Secret Vault에서 저장된 Google 액세스 토큰을 가져와 Google API를 호출하고 백엔드 작업을 자동화할 수 있습니다 (예: Google Drive 파일 관리, Calendar 이벤트 생성, Gmail을 통한 이메일 발송 등). API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요. + +## 사용자의 Google 아이덴티티 관리 \{#manage-user-s-google-identity} + +사용자가 Google 계정을 연결한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다: + +1. Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다. +2. **소셜 연결** 항목에서 Google 항목을 찾아 **관리**를 클릭하세요. +3. 이 페이지에서 관리자는 사용자의 Google 연결을 관리하고, Google 계정에서 제공 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 상태를 점검할 수 있습니다. + +## 참고 자료 \{#reference} Google Identity: OAuth 2.0 설정 + + + Google Identity Services (One Tap) + + +Google Cloud Console diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index 251904a8e06..f3a064cf897 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## Google API Console 에서 프로젝트 설정하기 \{#set-up-a-project-in-the-google-api-console} +## 1단계: Google Auth Platform에서 프로젝트 생성 \{#step-1-create-a-project-on-google-auth-platform} + +Google을 인증 (Authentication) 제공자로 사용하기 전에, Google Cloud Console에서 프로젝트를 설정하여 OAuth 2.0 자격 증명을 받아야 합니다. 이미 프로젝트가 있다면 이 단계는 건너뛰세요. + +1. [Google Cloud Console](https://console.cloud.google.com/)에 방문하여 Google 계정으로 로그인하세요. +2. 상단 메뉴 바에서 **프로젝트 선택** 버튼을 클릭한 후, **새 프로젝트** 버튼을 클릭하여 프로젝트를 생성하세요. +3. 새로 생성한 프로젝트에서 **API 및 서비스 > OAuth 동의 화면**으로 이동하여 앱을 구성하세요: + - **앱 정보**: 동의 페이지에 표시될 **애플리케이션 이름**과 **지원 이메일**을 입력하세요. + - **대상 (Audience)**: 원하는 대상 유형을 선택하세요: + - **내부 (Internal)** - 조직 내 Google Workspace 사용자만 사용 가능 + - **외부 (External)** - 모든 Google 사용자 사용 가능 (프로덕션 사용 시 검증 필요) + - **연락처 정보**: Google이 프로젝트 변경 사항을 알릴 수 있도록 이메일 주소를 입력하세요. + - **Google 정책에 동의합니다**를 체크하여 기본 설정을 완료하세요. +4. 선택적으로, **브랜딩** 섹션으로 이동하여 제품 정보와 **앱 로고**를 업로드할 수 있습니다. 이 로고는 OAuth 동의 화면에 표시되어 사용자가 앱을 인식하는 데 도움이 됩니다. + +:::tip +**외부 (External)** 대상 유형을 선택한 경우, 개발 중에는 테스트 사용자를 추가해야 하며, 프로덕션 사용을 위해 앱을 게시해야 합니다. +::: + +## 2단계: OAuth 2.0 자격 증명 생성 \{#step-2-create-oauth-2-0-credentials} + +Google Cloud Console의 [자격 증명](https://console.cloud.google.com/apis/credentials) 페이지로 이동하여 애플리케이션용 OAuth 자격 증명을 생성하세요. + +1. **자격 증명 만들기 > OAuth 클라이언트 ID**를 클릭하세요. +2. 애플리케이션 유형으로 **웹 애플리케이션**을 선택하세요. +3. OAuth 클라이언트의 **이름**을 입력하세요. 이 이름은 자격 증명을 식별하는 용도로만 사용되며, 최종 사용자에게는 표시되지 않습니다. +4. 허용된 URI를 구성하세요: + - **허용된 JavaScript 원본**: Logto 인스턴스의 origin을 추가하세요 (예: `https://your-logto-domain.com`) + - **허용된 리디렉션 URI**: Logto **Callback URI**를 추가하세요 (Logto Google 커넥터에서 복사) +5. **만들기**를 클릭하여 OAuth 클라이언트를 생성하세요. + +## 3단계: Logto 커넥터에 자격 증명 입력 \{#step-3-configure-logto-connector-with-credentials} + +OAuth 클라이언트 생성 후, Google이 자격 증명이 표시된 모달을 보여줍니다: + +1. **클라이언트 ID**를 복사하여 Logto의 `clientId` 필드에 붙여넣으세요. +2. **클라이언트 시크릿**을 복사하여 Logto의 `clientSecret` 필드에 붙여넣으세요. +3. Logto에서 **저장 및 완료**를 클릭하여 아이덴티티 시스템을 Google과 연결하세요. + +:::warning +클라이언트 시크릿은 안전하게 보관하고, 클라이언트 측 코드에 노출하지 마세요. 유출 시 즉시 새로 생성하세요. +::: + +## 4단계: 스코프(Scope) 구성 \{#step-4-configure-scopes} + +스코프 (Scope)는 앱이 사용자에게 요청하는 권한을 정의하며, 앱이 Google 계정에서 접근할 수 있는 데이터를 제어합니다. + +### Google Cloud Console에서 스코프 구성 \{#configure-scopes-in-google-cloud-console} + +1. **API 및 서비스 > OAuth 동의 화면 > 스코프**로 이동하세요. +2. **스코프 추가 또는 제거**를 클릭하고, 앱에 필요한 스코프만 선택하세요: + - **인증 (Authentication) (필수)**: + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **API 접근 (선택 사항)**: 앱에 필요한 추가 스코프를 추가하세요 (예: Drive, Calendar, YouTube). 사용 가능한 서비스를 찾으려면 [Google API 라이브러리](https://console.cloud.google.com/apis/library)를 참조하세요. 기본 권한 외에 Google API 접근이 필요하다면, 먼저 Google API 라이브러리에서 해당 API (예: Google Drive API, Gmail API, Calendar API)를 활성화하세요. +3. **업데이트**를 클릭하여 선택을 확정하세요. +4. **저장 및 계속**을 클릭하여 변경 사항을 적용하세요. -- [Google API Console](https://console.developers.google.com) 에 방문하여 Google 계정으로 로그인하세요. -- 상단 메뉴 바에서 **프로젝트 선택** 버튼을 클릭하고, **새 프로젝트** 버튼을 클릭하여 프로젝트를 생성하세요. -- 새로 생성된 프로젝트에서 **APIs & Services**를 클릭하여 **APIs & Services** 메뉴로 들어가세요. +### Logto에서 스코프 구성 \{#configure-scopes-in-logto} -## 동의 화면 구성하기 \{#configure-your-consent-screen} +필요에 따라 다음 방법 중 하나 이상을 선택하세요: -### 애플리케이션 구성 및 등록하기 \{#configure-and-register-your-application} +**옵션 1: 추가 API 스코프가 필요 없는 경우** -- 왼쪽 **APIs & Services** 메뉴에서 **OAuth 동의 화면** 버튼을 클릭하세요. -- 원하는 **사용자 유형**을 선택하고 **생성** 버튼을 클릭하세요. (참고: **외부**를 **사용자 유형**으로 선택한 경우, 나중에 테스트 사용자를 추가해야 합니다.) +- Logto Google 커넥터의 `Scopes` 필드를 비워두세요. +- 기본 스코프 `openid profile email`이 요청되어 Logto가 기본 사용자 정보를 올바르게 가져올 수 있습니다. -이제 **앱 등록 편집** 페이지에 있습니다. +**옵션 2: 로그인 시 추가 스코프 요청** -### 앱 등록 편집하기 \{#edit-app-registration} +- 원하는 모든 스코프를 **Scopes** 필드에 공백으로 구분하여 입력하세요. +- 여기에 입력한 스코프는 기본값을 덮어쓰므로, 항상 인증 (Authentication) 스코프도 포함하세요: `https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`. +- 전체 스코프 URL을 사용하세요. 예시: `https://www.googleapis.com/auth/calendar.readonly`. -#### OAuth 동의 화면 구성하기 \{#config-oauth-consent-screen} +**옵션 3: 나중에 점진적으로 스코프 요청** -- 지침에 따라 **OAuth 동의 화면** 양식을 작성하세요. -- **저장 후 계속**을 클릭하여 계속 진행하세요. +- 사용자가 로그인한 후, 소셜 인가 (Authorization) 플로우를 다시 시작하고 사용자의 저장된 토큰 세트를 업데이트하여 추가 스코프를 필요에 따라 요청할 수 있습니다. +- 이 추가 스코프는 Logto Google 커넥터의 `Scopes` 필드에 미리 입력할 필요가 없으며, Logto의 소셜 인증 (Authentication) API를 통해 달성할 수 있습니다. -#### 스코프 구성하기 \{#config-scopes} +이 단계를 따르면, Logto Google 커넥터는 앱에 꼭 필요한 권한만 요청하게 됩니다. -- **스코프 추가 또는 제거**를 클릭하고 팝업 드로어에서 `../auth/userinfo.email`, `../auth/userinfo.profile` 및 `openid`를 선택한 후 **업데이트**를 클릭하여 완료하세요. 사용 가능한 모든 스코프를 추가하는 것이 좋습니다. 그렇지 않으면 구성에 추가한 일부 스코프가 작동하지 않을 수 있습니다. -- 필요한 대로 양식을 작성하세요. -- **저장 후 계속**을 클릭하여 계속 진행하세요. +:::tip +앱이 Google API에 접근하여 작업을 수행하려면, Logto Google 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요. +::: -#### 테스트 사용자 추가하기 (외부 사용자 유형만 해당) \{#add-test-users-external-user-type-only} +## 5단계: 인증 (Authentication) 프롬프트 커스터마이즈 \{#step-5-customize-authentication-prompts} -- **사용자 추가**를 클릭하고 테스트 사용자를 추가하여 이 사용자가 테스트 중에 애플리케이션에 접근할 수 있도록 하세요. -- **저장 후 계속**을 클릭하여 계속 진행하세요. +Logto에서 **Prompts**를 구성하여 사용자 인증 (Authentication) 경험을 제어하세요. Prompts는 사용자 상호작용 유형을 지정하는 문자열 배열입니다: -이제 Google OAuth 2.0 동의 화면이 구성되었습니다. +- `none` - 인가 (Authorization) 서버가 인증 (Authentication) 또는 동의 화면을 표시하지 않습니다. 사용자가 이미 인증 (Authentication)되어 있지 않거나 요청된 스코프에 대해 사전 동의하지 않은 경우 오류를 반환합니다. 기존 인증 (Authentication) 및/또는 동의 여부를 확인할 때 사용하세요. +- `consent` - 인가 (Authorization) 서버가 정보를 클라이언트에 반환하기 전에 사용자에게 동의를 요청합니다. Google API 접근을 위한 **오프라인 접근**을 활성화하려면 필요합니다. +- `select_account` - 인가 (Authorization) 서버가 사용자에게 계정 선택을 요청합니다. 여러 Google 계정을 가진 사용자가 인증 (Authentication)할 계정을 선택할 수 있습니다. -## OAuth 2.0 자격 증명 얻기 \{#obtain-oauth-20-credentials} +## 6단계: 일반 설정 \{#step-6-general-settings} -- 왼쪽 **APIs & Services** 메뉴에서 **자격 증명** 버튼을 클릭하세요. -- **자격 증명** 페이지에서 상단 메뉴 바의 **+ 자격 증명 생성** 버튼을 클릭하고 **OAuth 클라이언트 ID**를 선택하세요. -- **OAuth 클라이언트 ID 생성** 페이지에서 애플리케이션 유형으로 **웹 애플리케이션**을 선택하세요. -- 애플리케이션의 기본 정보를 작성하세요. -- **+ URI 추가**를 클릭하여 **승인된 JavaScript 출처** 섹션에 승인된 도메인을 추가하세요. 이는 logto 인증 페이지가 제공될 도메인입니다. 우리의 경우, 이는 `${your_logto_origin}`이 됩니다. 예: `https://logto.dev`. -- **승인된 리디렉션 URI** 섹션에서 **+ URI 추가**를 클릭하여 **승인된 리디렉션 URI**를 설정하세요. 이는 로그인 후 사용자를 애플리케이션으로 리디렉션합니다. 우리의 경우, 이는 `${your_logto_endpoint}/callback/${connector_id}`가 됩니다. 예: `https://logto.dev/callback/${connector_id}`. `connector_id`는 Logto Admin Console 커넥터 세부 정보 페이지의 상단 바에서 찾을 수 있습니다. -- **생성**을 클릭하여 완료한 후 **클라이언트 ID**와 **클라이언트 비밀**을 얻을 수 있습니다. +다음은 Google 연결에는 영향을 주지 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다. -## 커넥터 구성하기 \{#configure-your-connector} +### 프로필 정보 동기화 \{#sync-profile-information} -이전 섹션에서 언급한 OAuth 앱 세부 정보 페이지에서 얻은 *클라이언트 ID*와 *클라이언트 비밀*로 `clientId`와 `clientSecret` 필드를 작성하세요. +Google 커넥터에서 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요: -`scope`는 [스코프](https://developers.google.com/identity/protocols/oauth2/scopes)의 공백으로 구분된 목록입니다. 제공되지 않으면, 기본적으로 `openid profile email`로 설정됩니다. +- **가입 시에만 동기화**: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다. +- **로그인할 때마다 항상 동기화**: 사용자가 로그인할 때마다 프로필 정보를 업데이트합니다. -`prompts`는 필요한 사용자 상호작용 유형을 지정하는 문자열 배열입니다. 문자열은 다음 값 중 하나일 수 있습니다: +### Google API 접근을 위한 토큰 저장 (선택 사항) \{#store-tokens-to-access-google-apis-optional} -- `none`: 인증 서버는 인증 또는 사용자 동의 화면을 표시하지 않습니다. 사용자가 이미 인증되지 않았거나 요청된 스코프에 대한 사전 구성된 동의가 없는 경우 오류를 반환합니다. 기존 인증 및 / 또는 동의를 확인하려면 none을 사용할 수 있습니다. -- `consent`: 인증 서버는 클라이언트에 정보를 반환하기 전에 사용자에게 동의를 요청합니다. -- `select_account`: 인증 서버는 사용자에게 사용자 계정을 선택하도록 요청합니다. 이는 인증 서버에 여러 계정이 있는 사용자가 현재 세션이 있는 여러 계정 중에서 선택할 수 있도록 합니다. +[Google API](https://console.cloud.google.com/apis/library)에 접근하여 사용자 권한으로 작업을 수행하려면 (소셜 로그인 또는 계정 연동 방식 모두), Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다. -### 구성 유형 \{#config-types} +1. Google Cloud Console OAuth 동의 화면 구성과 Logto Google 커넥터에 필요한 스코프를 추가하세요. +2. Logto Google 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 활성화하세요. Logto는 Google 액세스 토큰 및 리프레시 토큰을 Secret Vault에 안전하게 저장합니다. +3. 리프레시 토큰이 반환되도록 하려면, Logto Google 커넥터를 다음과 같이 구성하세요: + - **Prompts**에 `consent`를 포함하세요. + - **오프라인 접근**을 활성화하세요. -| 이름 | 유형 | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +Logto의 `Scope` 필드에 `offline_access`를 추가할 필요가 없습니다. 추가하면 오류가 발생할 수 있습니다. Google은 오프라인 접근이 활성화되면 자동으로 `access_type=offline`을 사용합니다. +::: -## Google One Tap 활성화하기 \{#enable-google-one-tap} +## 7단계: Google One Tap 활성화 (선택 사항) \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features)은 사용자가 Google 계정으로 웹사이트나 앱에 로그인할 수 있는 안전하고 쉬운 방법입니다. +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features)은 팝업 인터페이스를 통해 사용자가 Google 계정으로 웹사이트에 간편하게 로그인할 수 있는 안전한 방법입니다. -Google 커넥터를 설정한 후, 커넥터 세부 정보 페이지에서 Google One Tap에 대한 카드를 볼 수 있습니다. 스위치를 전환하여 가입 및 로그인 페이지에서 Google One Tap을 활성화할 수 있습니다. +Google 커넥터 설정이 완료되면, 커넥터 상세 페이지에서 Google One Tap 카드를 볼 수 있습니다. 스위치를 토글하여 Google One Tap을 활성화하세요. -Google One Tap을 활성화하면 다음 옵션을 구성할 수 있습니다: +### Google One Tap 구성 옵션 \{#google-one-tap-configuration-options} -- **가능한 경우 자격 증명 자동 선택**: [특정 조건이 충족되면](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) Google 계정으로 사용자를 자동으로 로그인합니다. -- **사용자가 외부를 클릭 / 탭하면 프롬프트 취소**: 사용자가 프롬프트 외부를 클릭하거나 탭하면 Google One Tap 프롬프트를 닫습니다. 비활성화된 경우, 사용자는 프롬프트를 닫기 위해 닫기 버튼을 클릭해야 합니다. -- **ITP 브라우저에서 업그레이드된 One Tap UX 활성화**: Intelligent Tracking Prevention (ITP) 브라우저에서 업그레이드된 Google One Tap 사용자 경험을 활성화합니다. 자세한 내용은 [이 페이지](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers)를 참조하세요. +- **가능하다면 자격 증명 자동 선택** - [특정 조건이 충족](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out)되면 Google 계정으로 자동 로그인합니다. +- **사용자가 바깥을 클릭/탭하면 프롬프트 취소** - 사용자가 프롬프트 바깥을 클릭/탭하면 Google One Tap 프롬프트를 닫습니다. 비활성화 시, 사용자가 닫기 버튼을 클릭해야 프롬프트가 사라집니다. +- **ITP 브라우저에서 업그레이드된 One Tap UX 활성화** - Intelligent Tracking Prevention (ITP) 브라우저에서 업그레이드된 Google One Tap 사용자 경험을 활성화합니다. 자세한 내용은 [이 문서](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers)를 참고하세요. -:::caution -서버 출처를 OAuth 동의 화면 구성의 **승인된 JavaScript 출처** 섹션에 추가해야 합니다. 그렇지 않으면 Google One Tap이 표시되지 않습니다. +:::warning +OAuth 클라이언트 구성의 **허용된 JavaScript 원본** 섹션에 도메인을 반드시 추가하세요. 그렇지 않으면 Google One Tap이 표시되지 않습니다. ::: +### Google One Tap의 중요한 제한 사항 \{#important-limitations-with-google-one-tap} + +**지속적인 API 접근을 위한 토큰 저장**과 **Google One Tap**을 동시에 활성화해도, 액세스 토큰이나 요청한 스코프를 자동으로 받을 수 없습니다. + +Google One Tap 로그인은 (표준 "Google로 로그인" 버튼과 달리) OAuth 액세스 토큰을 발급하지 않습니다. 대신, 사용자의 아이덴티티를 검증하는 ID 토큰 (서명된 JWT)만 반환하며, API 접근 권한은 부여하지 않습니다. + +Google One Tap 사용자가 Google API에 접근하려면, Logto의 소셜 인증 (Authentication) API를 사용하여 사용자가 Google One Tap으로 로그인한 후 소셜 인가 (Authorization) 플로우를 다시 시작할 수 있습니다. 이를 통해 필요한 추가 스코프를 요청하고 사용자의 저장된 토큰 세트를 업데이트할 수 있으며, Logto Google 커넥터에 미리 스코프를 입력할 필요가 없습니다. 이 방식은 점진적 인가 (Authorization)를 가능하게 하여, 앱이 실제로 필요할 때만 추가 권한을 요청할 수 있습니다. + +[Google One Tap 제한 사항](https://developers.google.com/identity/gsi/web/guides/overview)에 대해 공식 문서에서 더 알아보세요. + +## 8단계: 앱 테스트 및 게시 \{#step-8-test-and-publish-your-app} + +### 내부 앱의 경우 \{#for-internal-apps} + +Google에서 **대상 (Audience)** 유형이 **내부 (Internal)**로 설정된 경우, 앱은 조직 내 Google Workspace 사용자만 사용할 수 있습니다. 조직 계정으로 테스트할 수 있습니다. + +### 외부 앱의 경우 \{#for-external-apps} + +**대상 (Audience)** 유형이 **외부 (External)**인 경우: + +1. **개발 중**: **OAuth 동의 화면 > 테스트 사용자**로 이동하여 테스트 사용자 이메일 주소를 추가하세요. 이 사용자만 앱에 로그인할 수 있습니다. +2. **프로덕션용**: OAuth 동의 화면 섹션에서 **앱 게시**를 클릭하여 모든 Google 계정 사용자가 사용할 수 있도록 하세요. + :::note -웹사이트에서 Google One Tap을 활성화하려면 (Logto 로그인 경험을 넘어), 이 기능은 개발 중입니다. 업데이트를 기대해 주세요. +민감하거나 제한된 스코프를 사용하는 앱은 게시 전에 Google의 검증이 필요할 수 있습니다. 이 과정은 몇 주가 소요될 수 있습니다. ::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index 2103ae9d4b8..7eae89143e5 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -1,11 +1,11 @@ --- slug: /integrations/oauth2 -sidebar_label: OAuth 2.0 (Social) +sidebar_label: OAuth 2.0 (소셜) sidebar_custom_props: - description: OAuth 2.0 인가 프레임워크는 제3자 애플리케이션이 HTTP 서비스에 제한된 접근을 얻을 수 있도록 합니다. + description: OAuth 2.0 인가 (Authorization) 프레임워크는 서드파티 애플리케이션이 HTTP 서비스에 제한된 접근을 얻을 수 있도록 합니다. logoFilename: 'oauth.svg' tutorial_name: OAuth2 -tutorial_config_name: 표준 OAuth 2.0 앱 +tutorial_config_name: Standard OAuth 2.0 app --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -14,17 +14,27 @@ import Integration from './_integration.mdx'; # OAuth 2.0 프로토콜로 소셜 로그인을 설정하세요 -OAuth 2.0 프로토콜에 대한 공식 Logto 커넥터입니다. +OAuth 2.0 프로토콜을 위한 공식 Logto 커넥터입니다. ## 시작하기 \{#get-started} -OAuth 커넥터는 OAuth 2.0 프로토콜을 지원하는 임의의 소셜 아이덴티티 제공자 (IdP)와 Logto의 연결을 가능하게 합니다. +OAuth 커넥터는 OAuth 2.0 프로토콜을 지원하는 임의의 소셜 아이덴티티 제공자 (IdP)와 Logto의 연결을 가능하게 합니다. OAuth 커넥터를 사용하여 애플리케이션에서 다음을 할 수 있습니다: + +- 소셜 로그인 버튼 추가 +- 사용자 계정을 소셜 아이덴티티에 연결 +- 소셜 제공자로부터 사용자 프로필 정보 동기화 +- Logto Secret Vault에 안전하게 토큰을 저장하여 자동화 작업 시 서드파티 API에 접근 (예: Google Docs 편집, 앱에서 Calendar 이벤트 관리 등) + +이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 OAuth 2.0 커넥터를 생성하세요: + +1. Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동합니다. +2. **소셜 커넥터 추가**를 클릭하고, **OAuth 2.0**을 선택한 후 **다음**을 클릭하고 단계별 튜토리얼을 따라 통합을 완료하세요. :::note -OAuth 커넥터는 Logto에서 특별한 종류의 커넥터로, 몇 가지 OAuth 프로토콜 기반 커넥터를 추가할 수 있습니다. +OAuth 커넥터는 Logto에서 특별한 종류의 커넥터로, 여러 개의 OAuth 프로토콜 기반 커넥터를 추가할 수 있습니다. ::: @@ -32,4 +42,4 @@ OAuth 커넥터는 Logto에서 특별한 종류의 커넥터로, 몇 가지 OAut ## 참고 자료 \{#reference} -OAuth 2.0 인가 프레임워크 +OAuth 2.0 인가 (Authorization) 프레임워크 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index ea6652cffe5..4cb4738ab29 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ -## OAuth 앱 생성 \{#create-your-oauth-app} +## OAuth 앱 생성하기 \{#create-your-oauth-app} -이 페이지를 열었을 때, 이미 연결하고자 하는 소셜 아이덴티티 제공자를 알고 있다고 믿습니다. 첫 번째로 해야 할 일은 아이덴티티 제공자가 OAuth 프로토콜을 지원하는지 확인하는 것입니다. 이는 유효한 커넥터를 구성하기 위한 전제 조건입니다. 그런 다음, 아이덴티티 제공자의 지침에 따라 OAuth 인가를 위한 관련 앱을 등록하고 생성하세요. +이 페이지를 열었다면 이미 연결하고자 하는 소셜 아이덴티티 제공자 (IdP)를 알고 있다고 생각합니다. 가장 먼저 해야 할 일은 해당 아이덴티티 제공자가 OAuth 프로토콜을 지원하는지 확인하는 것입니다. 이는 유효한 커넥터를 구성하기 위한 전제 조건입니다. 그런 다음, 아이덴티티 제공자의 안내에 따라 OAuth 인가를 위한 관련 앱을 등록 및 생성하세요. -## 커넥터 구성 \{#configure-your-connector} +## 커넥터 구성하기 \{#configure-your-connector} -보안상의 이유로 "Authorization Code" 그랜트 타입만 지원하며, 이는 Logto의 시나리오에 완벽하게 맞습니다. +보안상의 이유로 "Authorization Code" 그랜트 타입만 지원하며, 이는 Logto의 시나리오에 완벽하게 적합합니다. -`clientId`와 `clientSecret`은 OAuth 앱의 세부 정보 페이지에서 찾을 수 있습니다. +`clientId`와 `clientSecret`은 OAuth 앱의 상세 페이지에서 확인할 수 있습니다. -_clientId_: 클라이언트 ID는 인가 서버와의 등록 중에 클라이언트 애플리케이션을 식별하는 고유 식별자입니다. 이 ID는 인가 서버가 클라이언트 애플리케이션의 아이덴티티를 확인하고, 특정 클라이언트 애플리케이션과 관련된 모든 인가된 액세스 토큰을 연결하는 데 사용됩니다. +_clientId_: 클라이언트 ID는 인가 서버에 등록할 때 클라이언트 애플리케이션을 식별하는 고유 식별자입니다. 이 ID는 인가 서버가 클라이언트 애플리케이션의 아이덴티티를 확인하고, 인가된 액세스 토큰을 해당 클라이언트 애플리케이션과 연결하는 데 사용됩니다. -_clientSecret_: 클라이언트 시크릿은 등록 중에 인가 서버에 의해 클라이언트 애플리케이션에 발급되는 기밀 키입니다. 클라이언트 애플리케이션은 액세스 토큰을 요청할 때 인가 서버에 자신을 인증하기 위해 이 시크릿 키를 사용합니다. 클라이언트 시크릿은 기밀 정보로 간주되며 항상 안전하게 보관되어야 합니다. +_clientSecret_: 클라이언트 시크릿은 인가 서버가 등록 시 클라이언트 애플리케이션에 발급하는 비밀 키입니다. 클라이언트 애플리케이션은 액세스 토큰을 요청할 때 이 비밀 키를 사용해 인가 서버에 자신을 인증합니다. 클라이언트 시크릿은 기밀 정보로 간주되며 항상 안전하게 보관해야 합니다. -_tokenEndpointAuthMethod_: 토큰 엔드포인트 인증 방법은 클라이언트 애플리케이션이 액세스 토큰을 요청할 때 인가 서버에 자신을 인증하는 데 사용됩니다. 지원되는 방법을 확인하려면 OAuth 2.0 서비스 제공자의 OpenID Connect 디스커버리 엔드포인트에서 사용할 수 있는 `token_endpoint_auth_methods_supported` 필드를 참조하거나 OAuth 2.0 서비스 제공자가 제공하는 관련 문서를 참조하세요. +_tokenEndpointAuthMethod_: 토큰 엔드포인트 인증 방식은 클라이언트 애플리케이션이 액세스 토큰을 요청할 때 인가 서버에 자신을 인증하는 데 사용됩니다. 지원되는 방식을 확인하려면 OAuth 2.0 서비스 제공자의 OpenID Connect 디스커버리 엔드포인트에서 제공되는 `token_endpoint_auth_methods_supported` 필드를 참조하거나, 해당 OAuth 2.0 서비스 제공자의 문서를 참고하세요. -_clientSecretJwtSigningAlgorithm (선택 사항)_: `tokenEndpointAuthMethod`가 `client_secret_jwt`일 때만 필요합니다. 클라이언트 시크릿 JWT 서명 알고리즘은 토큰 요청 중에 인가 서버에 전송되는 JWT를 클라이언트 애플리케이션이 서명하는 데 사용됩니다. +_clientSecretJwtSigningAlgorithm (선택 사항)_: `tokenEndpointAuthMethod`가 `client_secret_jwt`인 경우에만 필요합니다. 클라이언트 시크릿 JWT 서명 알고리즘은 토큰 요청 시 클라이언트 애플리케이션이 인가 서버로 전송하는 JWT에 서명하는 데 사용됩니다. -_scope_: 스코프 매개변수는 클라이언트 애플리케이션이 접근을 요청하는 리소스와 권한의 집합을 지정하는 데 사용됩니다. 스코프 매개변수는 일반적으로 특정 권한을 나타내는 값의 공백으로 구분된 목록으로 정의됩니다. 예를 들어, "read write"라는 스코프 값은 클라이언트 애플리케이션이 사용자의 데이터에 대한 읽기 및 쓰기 접근을 요청하고 있음을 나타낼 수 있습니다. +_scope_: 스코프 파라미터는 클라이언트 애플리케이션이 접근을 요청하는 리소스와 권한의 집합을 지정하는 데 사용됩니다. 스코프 파라미터는 일반적으로 특정 권한을 나타내는 값들을 공백으로 구분한 리스트로 정의됩니다. 예를 들어, "read write"라는 스코프 값은 클라이언트 애플리케이션이 사용자의 데이터에 대한 읽기 및 쓰기 접근을 요청함을 의미할 수 있습니다. -소셜 벤더의 문서에서 `authorizationEndpoint`, `tokenEndpoint` 및 `userInfoEndpoint`를 찾을 수 있습니다. +`authorizationEndpoint`, `tokenEndpoint`, `userInfoEndpoint`는 소셜 벤더의 문서에서 확인할 수 있습니다. -_authenticationEndpoint_: 이 엔드포인트는 인증 과정을 시작하는 데 사용됩니다. 인증 과정은 일반적으로 사용자가 로그인하고 클라이언트 애플리케이션이 자신의 리소스에 접근할 수 있도록 인가를 부여하는 것을 포함합니다. +_authenticationEndpoint_: 이 엔드포인트는 인증 (Authentication) 프로세스를 시작하는 데 사용됩니다. 인증 과정은 일반적으로 사용자가 로그인하고, 클라이언트 애플리케이션이 리소스에 접근할 수 있도록 인가를 부여하는 과정을 포함합니다. -_tokenEndpoint_: 이 엔드포인트는 클라이언트 애플리케이션이 요청된 리소스에 접근할 수 있는 액세스 토큰을 얻는 데 사용됩니다. 클라이언트 애플리케이션은 일반적으로 그랜트 타입과 인가 코드를 포함한 요청을 토큰 엔드포인트에 보내 액세스 토큰을 받습니다. +_tokenEndpoint_: 이 엔드포인트는 클라이언트 애플리케이션이 요청한 리소스에 접근할 수 있는 액세스 토큰을 얻는 데 사용됩니다. 클라이언트 애플리케이션은 일반적으로 그랜트 타입과 인가 코드를 포함한 요청을 토큰 엔드포인트로 전송하여 액세스 토큰을 받습니다. -_userInfoEndpoint_: 이 엔드포인트는 클라이언트 애플리케이션이 사용자의 전체 이름, 이메일 주소 또는 프로필 사진과 같은 추가 정보를 얻는 데 사용됩니다. 사용자 정보 엔드포인트는 일반적으로 클라이언트 애플리케이션이 토큰 엔드포인트에서 액세스 토큰을 얻은 후에 접근됩니다. +_userInfoEndpoint_: 이 엔드포인트는 클라이언트 애플리케이션이 사용자에 대한 추가 정보(예: 전체 이름, 이메일 주소, 프로필 사진 등)를 얻는 데 사용됩니다. 일반적으로 클라이언트 애플리케이션이 토큰 엔드포인트에서 액세스 토큰을 받은 후 접근합니다. -Logto는 또한 사용자가 일반적으로 표준이 아닌 소셜 벤더의 프로필에서 매핑을 사용자 정의할 수 있는 `profileMap` 필드를 제공합니다. 키는 Logto의 표준 사용자 프로필 필드 이름이며, 해당 값은 소셜 프로필의 필드 이름이어야 합니다. 현재 단계에서는 Logto가 소셜 프로필에서 'id', 'name', 'avatar', 'email' 및 'phone'에만 관심을 가지며, 'id'만 필수 필드이고 나머지는 선택 사항입니다. +Logto는 또한 소셜 벤더의 프로필 매핑이 표준이 아닌 경우를 위해 `profileMap` 필드를 제공합니다. 키는 Logto의 표준 사용자 프로필 필드명이고, 값은 소셜 프로필의 필드명이어야 합니다. 현재 단계에서는 Logto가 소셜 프로필에서 'id', 'name', 'avatar', 'email', 'phone'만을 고려하며, 'id'만 필수이고 나머지는 선택 필드입니다. -`responseType`과 `grantType`은 인가 코드 그랜트 타입과 함께 고정된 값만 사용할 수 있으므로 선택 사항이며 기본 값이 자동으로 채워집니다. +`responseType`과 `grantType`은 오직 authorization code grant type에서만 고정 값이 될 수 있으므로, 선택 사항으로 두고 기본값이 자동으로 채워집니다. -예를 들어, [Google 사용자 프로필 응답](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload)을 찾을 수 있으며, 따라서 `profileMap`은 다음과 같아야 합니다: +예를 들어, [Google 사용자 프로필 응답](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload)을 참고하면, 해당 `profileMap`은 다음과 같아야 합니다: ```json { @@ -41,14 +41,14 @@ Logto는 또한 사용자가 일반적으로 표준이 아닌 소셜 벤더의 :::note -사용자 정의 매개변수를 넣기 위한 선택적 `customConfig` 키를 제공했습니다. -각 소셜 아이덴티티 제공자는 OAuth 표준 프로토콜에 대한 자체 변형을 가질 수 있습니다. 원하는 소셜 아이덴티티 제공자가 OAuth 표준 프로토콜을 엄격히 준수한다면, `customConfig`에 대해 신경 쓸 필요가 없습니다. +사용자 정의 파라미터를 넣을 수 있도록 OPTIONAL `customConfig` 키를 제공합니다. +각 소셜 아이덴티티 제공자는 OAuth 표준 프로토콜에 대해 자체 변형을 가질 수 있습니다. 만약 원하는 소셜 아이덴티티 제공자가 OAuth 표준 프로토콜을 엄격히 준수한다면, `customConfig`는 신경 쓰지 않아도 됩니다. ::: -## 구성 유형 \{#config-types} +## 구성 타입 \{#config-types} -| 이름 | 유형 | 필수 여부 | +| 이름 | 타입 | 필수 여부 | | ------------------------- | ----------------------- | --------- | | authorizationEndpoint | string | true | | userInfoEndpoint | string | true | @@ -62,10 +62,76 @@ Logto는 또한 사용자가 일반적으로 표준이 아닌 소셜 벤더의 | customConfig | Record\ | false | | profileMap | ProfileMap | false | -| ProfileMap 필드 | 유형 | 필수 여부 | 기본 값 | -| --------------- | ------ | --------- | ------- | -| id | string | false | id | -| name | string | false | name | -| avatar | string | false | avatar | -| email | string | false | email | -| phone | string | false | phone | +| ProfileMap 필드 | 타입 | 필수 여부 | 기본값 | +| --------------- | ------ | --------- | ------ | +| id | string | false | id | +| name | string | false | name | +| avatar | string | false | avatar | +| email | string | false | email | +| phone | string | false | phone | + +## 일반 설정 \{#general-settings} + +다음은 아이덴티티 제공자와의 연결을 막지는 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다. + +### 소셜 버튼 이름 및 로고 \{#social-button-name-and-logo} + +로그인 페이지에 소셜 버튼을 표시하고 싶다면, 소셜 아이덴티티 제공자의 **이름**과 **로고**(다크 모드 및 라이트 모드)를 설정할 수 있습니다. 이를 통해 사용자가 소셜 로그인 옵션을 쉽게 인식할 수 있습니다. + +### 아이덴티티 제공자 이름 \{#identity-provider-name} + +각 소셜 커넥터는 사용자 아이덴티티를 구분하기 위해 고유한 아이덴티티 제공자 (IdP) 이름을 가집니다. 일반 커넥터는 고정된 IdP 이름을 사용하지만, 커스텀 커넥터는 고유한 값을 필요로 합니다. 자세한 내용은 [IdP 이름](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) 문서를 참고하세요. + +### 프로필 정보 동기화 \{#sync-profile-information} + +OAuth 커넥터에서는 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요: + +- **가입 시에만 동기화**: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다. +- **로그인 시마다 항상 동기화**: 사용자가 로그인할 때마다 프로필 정보를 업데이트합니다. + +### 타사 API 접근을 위한 토큰 저장 (선택 사항) \{#store-tokens-to-access-third-party-apis-optional} + +아이덴티티 제공자의 API에 접근하여 사용자 인가로 작업을 수행하려면(소셜 로그인 또는 계정 연동을 통해), Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다. + +1. 위의 안내에 따라 **scope** 필드에 필요한 스코프를 추가하세요. +2. Logto OAuth 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 활성화하세요. Logto는 액세스 토큰을 Secret Vault에 안전하게 저장합니다. +3. **표준** OAuth/OIDC 아이덴티티 제공자의 경우, 리프레시 토큰을 얻으려면 반드시 `offline_access` 스코프를 포함해야 하며, 이를 통해 반복적인 사용자 동의 요청을 방지할 수 있습니다. + +:::warning +클라이언트 시크릿을 안전하게 보관하고, 절대 클라이언트 측 코드에 노출하지 마세요. 유출 시, 즉시 아이덴티티 제공자의 앱 설정에서 새로 발급받으세요. +::: + +## OAuth 커넥터 활용하기 \{#utilize-the-oauth-connector} + +OAuth 커넥터를 생성하고 아이덴티티 제공자와 연결한 후, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요: + +### 소셜 로그인 버튼 활성화 \{#enable-social-sign-in-button} + +1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요. +2. **소셜 로그인** 섹션에서 OAuth 커넥터를 추가하여 사용자가 아이덴티티 제공자로 인증 (Authentication)할 수 있도록 하세요. + +[social sign-in experience](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in)에 대해 더 알아보세요. + +### 소셜 계정 연결 또는 연결 해제 \{#link-or-unlink-a-social-account} + +Account API를 사용하여 앱 내에 맞춤형 계정 센터를 구축하고, 로그인한 사용자가 소셜 계정을 연결하거나 해제할 수 있도록 하세요. [Account API 튜토리얼 따라하기](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +소셜 로그인 활성화 없이 계정 연동 및 API 접근만을 위해 OAuth 커넥터를 활성화하는 것도 가능합니다. +::: + +### 아이덴티티 제공자 API 접근 및 작업 수행 \{#access-identity-provider-apis-and-perform-actions} + +애플리케이션은 Secret Vault에서 저장된 액세스 토큰을 가져와 아이덴티티 제공자의 API를 호출하고 백엔드 작업을 자동화할 수 있습니다. 구체적인 기능은 아이덴티티 제공자와 요청한 스코프에 따라 다릅니다. API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요. + +## 사용자의 소셜 아이덴티티 관리 \{#manage-user-s-social-identity} + +사용자가 소셜 계정을 연동한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다: + +1. Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다. +2. **소셜 연결** 섹션에서 아이덴티티 제공자 항목을 찾아 **관리**를 클릭하세요. +3. 이 페이지에서 관리자는 사용자의 소셜 연결을 관리하고, 소셜 계정에서 부여 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 상태를 점검할 수 있습니다. + +:::note +일부 아이덴티티 제공자의 액세스 토큰 응답에는 특정 스코프 정보가 포함되어 있지 않아, Logto가 사용자가 부여한 권한 목록을 직접 표시할 수 없습니다. 그러나 사용자가 인가 과정에서 요청된 스코프에 동의했다면, 애플리케이션은 OAuth API 접근 시 해당 권한을 갖게 됩니다. +::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index 8a2c5334806..ab3eb663b9d 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -1,8 +1,8 @@ --- slug: /integrations/oidc -sidebar_label: OIDC (Social) +sidebar_label: OIDC (소셜) sidebar_custom_props: - description: OpenID Connect 1.0은 OAuth 2.0 프로토콜 위에 간단한 아이덴티티 레이어입니다. + description: OpenID Connect 1.0은 OAuth 2.0 프로토콜 위에 구축된 간단한 아이덴티티 계층입니다. tutorial_name: OIDC tutorial_config_name: Standard OIDC app --- @@ -11,19 +11,29 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# OpenID Connect (OIDC)로 소셜 로그인을 설정하세요 +# OpenID Connect (OIDC) 소셜 로그인을 설정하세요 -OpenID Connect (OIDC) 프로토콜에 대한 공식 Logto 커넥터입니다. +OpenID Connect (OIDC) 프로토콜을 위한 공식 Logto 커넥터입니다. ## 시작하기 \{#get-started} -OIDC 커넥터는 Logto가 OIDC 프로토콜을 지원하는 임의의 소셜 아이덴티티 제공자 (IdP)와 연결할 수 있도록 합니다. +OIDC 커넥터는 Logto가 OIDC 프로토콜을 지원하는 임의의 소셜 아이덴티티 제공자와 연결할 수 있도록 해줍니다. OIDC 커넥터를 사용하면 애플리케이션에서 다음과 같은 작업을 할 수 있습니다: + +- 소셜 로그인 버튼 추가 +- 사용자 계정을 소셜 아이덴티티에 연결 +- 소셜 제공자로부터 사용자 프로필 정보 동기화 +- Logto Secret Vault에 안전하게 토큰을 저장하여 자동화 작업(예: Google Docs 편집, 앱 내 캘린더 이벤트 관리 등)을 위한 서드파티 API 접근 + +이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 OIDC 커넥터를 생성하세요: + +1. Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동합니다. +2. **소셜 커넥터 추가**를 클릭하고, **OIDC**를 선택한 후 **다음**을 클릭하여 단계별 튜토리얼을 따라 통합을 완료하세요. :::note -OIDC 커넥터는 Logto에서 특별한 종류의 커넥터로, 몇 가지 OIDC 기반 커넥터를 추가할 수 있습니다. +OIDC 커넥터는 Logto에서 특별한 종류의 커넥터로, 여러 개의 OIDC 프로토콜 기반 커넥터를 추가할 수 있습니다. ::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index 0dddb4b8f6d..db15d9d0bd4 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,45 +1,45 @@ ## OIDC 앱 생성하기 \{#create-your-oidc-app} -이 페이지를 열었을 때, 이미 연결하고자 하는 소셜 아이덴티티 제공자를 알고 있다고 믿습니다. 가장 먼저 해야 할 일은 아이덴티티 제공자가 OIDC 프로토콜을 지원하는지 확인하는 것입니다. 이는 유효한 커넥터를 구성하기 위한 전제 조건입니다. 그런 다음, 아이덴티티 제공자의 지침에 따라 OIDC 인가를 위한 관련 앱을 등록하고 생성하세요. +이 페이지를 열었을 때, 이미 연결하고자 하는 소셜 아이덴티티 제공자 (IdP)를 알고 있다고 가정합니다. 가장 먼저 해야 할 일은 해당 아이덴티티 제공자가 OIDC 프로토콜을 지원하는지 확인하는 것입니다. 이는 유효한 커넥터를 구성하기 위한 전제 조건입니다. 그런 다음, 아이덴티티 제공자의 안내에 따라 OIDC 인가를 위한 관련 앱을 등록 및 생성하세요. ## 커넥터 구성하기 \{#configure-your-connector} -보안상의 이유로 "Authorization Code" 그랜트 타입만 지원하며, 이는 Logto의 시나리오에 완벽하게 맞습니다. +보안상의 이유로 "Authorization Code" 그랜트 타입만 지원하며, 이는 Logto의 시나리오에 완벽하게 부합합니다. -`clientId`와 `clientSecret`은 OIDC 앱의 세부 정보 페이지에서 찾을 수 있습니다. +`clientId`와 `clientSecret`은 OIDC 앱의 상세 페이지에서 확인할 수 있습니다. -_clientId_: 클라이언트 ID는 인가 서버에 등록할 때 클라이언트 애플리케이션을 식별하는 고유 식별자입니다. 이 ID는 인가 서버가 클라이언트 애플리케이션의 아이덴티티를 확인하고, 특정 클라이언트 애플리케이션과 관련된 모든 인가된 액세스 토큰을 연결하는 데 사용됩니다. +_clientId_: 클라이언트 ID는 인가 서버에 등록할 때 클라이언트 애플리케이션을 식별하는 고유 식별자입니다. 이 ID는 인가 서버가 클라이언트 애플리케이션의 아이덴티티를 확인하고, 인가된 액세스 토큰을 해당 클라이언트 애플리케이션과 연관시키는 데 사용됩니다. -_clientSecret_: 클라이언트 시크릿은 인가 서버가 등록 시 클라이언트 애플리케이션에 발급하는 기밀 키입니다. 클라이언트 애플리케이션은 이 시크릿 키를 사용하여 인가 서버에 액세스 토큰을 요청할 때 자신을 인증합니다. 클라이언트 시크릿은 기밀 정보로 간주되며 항상 안전하게 보관되어야 합니다. +_clientSecret_: 클라이언트 시크릿은 인가 서버가 등록 시 클라이언트 애플리케이션에 발급하는 비밀 키입니다. 클라이언트 애플리케이션은 이 시크릿 키를 사용하여 액세스 토큰을 요청할 때 인가 서버에 자신을 인증합니다. 클라이언트 시크릿은 기밀 정보이므로 항상 안전하게 보관해야 합니다. -_tokenEndpointAuthMethod_: 토큰 엔드포인트 인증 방법은 클라이언트 애플리케이션이 액세스 토큰을 요청할 때 인가 서버에 자신을 인증하는 데 사용됩니다. 지원되는 방법을 확인하려면 OAuth 2.0 서비스 제공자의 OpenID Connect 디스커버리 엔드포인트에서 `token_endpoint_auth_methods_supported` 필드를 참조하거나, OAuth 2.0 서비스 제공자가 제공하는 관련 문서를 참조하세요. +_tokenEndpointAuthMethod_: 토큰 엔드포인트 인증 방식은 클라이언트 애플리케이션이 액세스 토큰을 요청할 때 인가 서버에 자신을 인증하는 데 사용됩니다. 지원되는 방식을 확인하려면 OAuth 2.0 서비스 제공자의 OpenID Connect 디스커버리 엔드포인트에서 `token_endpoint_auth_methods_supported` 필드를 참조하거나, 해당 OAuth 2.0 서비스 제공자의 문서를 확인하세요. -_clientSecretJwtSigningAlgorithm (선택 사항)_: `tokenEndpointAuthMethod`가 `client_secret_jwt`일 때만 필요합니다. 클라이언트 시크릿 JWT 서명 알고리즘은 클라이언트 애플리케이션이 토큰 요청 중에 인가 서버에 전송하는 JWT를 서명하는 데 사용됩니다. +_clientSecretJwtSigningAlgorithm (선택 사항)_: `tokenEndpointAuthMethod`가 `client_secret_jwt`일 때만 필요합니다. 클라이언트 시크릿 JWT 서명 알고리즘은 토큰 요청 중 클라이언트 애플리케이션이 인가 서버로 전송하는 JWT를 서명하는 데 사용됩니다. -_scope_: 스코프 매개변수는 클라이언트 애플리케이션이 접근을 요청하는 리소스와 권한의 집합을 지정하는 데 사용됩니다. 스코프 매개변수는 일반적으로 특정 권한을 나타내는 값의 공백으로 구분된 목록으로 정의됩니다. 예를 들어, "read write"라는 스코프 값은 클라이언트 애플리케이션이 사용자의 데이터에 대한 읽기 및 쓰기 접근을 요청하고 있음을 나타낼 수 있습니다. +_scope_: 스코프 파라미터는 클라이언트 애플리케이션이 접근을 요청하는 리소스와 권한의 집합을 지정하는 데 사용됩니다. 스코프 파라미터는 일반적으로 특정 권한을 나타내는 값들의 공백으로 구분된 목록으로 정의됩니다. 예를 들어, "read write"라는 스코프 값은 클라이언트 애플리케이션이 사용자의 데이터에 대한 읽기 및 쓰기 권한을 요청함을 나타낼 수 있습니다. -`authorizationEndpoint`, `tokenEndpoint`, `jwksUri` 및 `issuer`를 OpenID Provider의 구성 정보로 찾을 수 있습니다. 이는 소셜 벤더의 문서에 제공되어야 합니다. +`authorizationEndpoint`, `tokenEndpoint`, `jwksUri`, `issuer`는 OpenID Provider의 구성 정보로, 소셜 벤더의 문서에서 확인할 수 있습니다. -_authenticationEndpoint_: 이 엔드포인트는 인증 과정을 시작하는 데 사용됩니다. 인증 과정은 일반적으로 사용자가 로그인하고 클라이언트 애플리케이션이 자신의 리소스에 접근할 수 있도록 인가를 부여하는 것을 포함합니다. +_authenticationEndpoint_: 이 엔드포인트는 인증 (Authentication) 프로세스를 시작하는 데 사용됩니다. 인증 과정은 일반적으로 사용자가 로그인하고, 클라이언트 애플리케이션이 리소스에 접근할 수 있도록 인가를 부여하는 과정을 포함합니다. -_tokenEndpoint_: 이 엔드포인트는 클라이언트 애플리케이션이 요청된 리소스에 접근할 수 있는 id 토큰을 얻기 위해 사용됩니다. 클라이언트 애플리케이션은 일반적으로 그랜트 타입과 인가 코드를 포함하여 토큰 엔드포인트에 요청을 보내 id 토큰을 받습니다. +_tokenEndpoint_: 이 엔드포인트는 클라이언트 애플리케이션이 요청한 리소스에 접근할 수 있는 id 토큰 (ID token)을 얻는 데 사용됩니다. 클라이언트 애플리케이션은 일반적으로 그랜트 타입과 인가 코드를 포함한 요청을 토큰 엔드포인트로 전송하여 id 토큰을 받습니다. -_jwksUri_: 이는 소셜 아이덴티티 제공자 (줄여서 IdP)의 JSON Web Key Set (JWKS)을 얻을 수 있는 URL 엔드포인트입니다. JWKS는 IdP가 인증 과정에서 발급하는 JSON Web Token (JWT)을 서명하고 검증하는 데 사용하는 암호화 키의 집합입니다. `jwksUri`는 의존 당사자 (RP)가 IdP가 JWT를 서명하는 데 사용하는 공개 키를 얻기 위해 사용되며, RP는 IdP로부터 받은 JWT의 진위성과 무결성을 검증할 수 있습니다. +_jwksUri_: 이 URL 엔드포인트는 소셜 아이덴티티 제공자 (IdP)의 JSON Web Key Set (JWKS)을 얻을 수 있는 위치입니다. JWKS는 IdP가 인증 (Authentication) 과정에서 발급하는 JSON Web Token (JWT)을 서명 및 검증하는 데 사용하는 암호화 키 집합입니다. `jwksUri`는 신뢰 당사자 (RP)가 IdP가 JWT를 서명하는 데 사용하는 공개 키를 얻는 데 사용되며, 이를 통해 RP는 IdP로부터 받은 JWT의 진위와 무결성을 검증할 수 있습니다. -_issuer_: 이는 IdP의 고유 식별자로, RP가 IdP로부터 받은 JWT를 검증하는 데 사용됩니다. 이는 JWT에 `iss` [클레임](https://www.rfc-editor.org/rfc/rfc7519#section-4)으로 포함됩니다 (Id 토큰은 항상 JWT입니다). 발급자 값은 IdP의 인가 서버 URL과 일치해야 하며, RP가 신뢰하는 URI여야 합니다. RP가 JWT를 받으면, `iss` 클레임을 확인하여 신뢰할 수 있는 IdP에 의해 발급되었는지, 그리고 JWT가 RP와 함께 사용하기 위한 것인지 확인합니다. +_issuer_: 이는 RP가 IdP로부터 받은 JWT를 검증할 때 사용하는 IdP의 고유 식별자입니다. JWT에는 `iss` [클레임 (Claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4)으로 포함됩니다 (ID 토큰은 항상 JWT입니다). issuer 값은 IdP의 인가 서버 URL과 일치해야 하며, RP가 신뢰하는 URI여야 합니다. RP가 JWT를 수신하면, `iss` 클레임을 확인하여 신뢰할 수 있는 IdP가 발급했는지, JWT가 RP에서 사용하기 위한 것인지 확인합니다. -`jwksUri`와 `issuer`는 인증 과정에서 최종 사용자의 아이덴티티를 검증하기 위한 안전한 메커니즘을 제공합니다. `jwksUri`에서 얻은 공개 키를 사용하여, RP는 IdP가 발급한 JWT의 진위성과 무결성을 검증할 수 있습니다. 발급자 값은 RP가 신뢰할 수 있는 IdP에 의해 발급된 JWT만 수락하고, JWT가 RP와 함께 사용하기 위한 것임을 보장합니다. +`jwksUri`와 `issuer`는 RP가 인증 (Authentication) 과정에서 최종 사용자의 아이덴티티를 검증할 수 있도록 하는 안전한 메커니즘을 제공합니다. RP는 `jwksUri`에서 얻은 공개 키를 사용하여 IdP가 발급한 JWT의 진위와 무결성을 검증할 수 있습니다. issuer 값은 RP가 신뢰하는 IdP가 발급한 JWT만 허용하도록 보장합니다. -항상 인증 요청이 필요하기 때문에, `authRequestOptionalConfig`가 모든 선택적 구성을 포괄하도록 제공됩니다. 자세한 내용은 [OIDC 인증 요청](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)을 참조하세요. 이 구성에서 `nonce`가 누락된 것을 발견할 수도 있습니다. `nonce`는 각 요청마다 동일해야 하므로, 우리는 `nonce`의 생성을 코드 구현에 포함시켰습니다. 그러니 걱정하지 마세요! 앞서 언급한 `jwksUri`와 `issuer`도 `idTokenVerificationConfig`에 포함되어 있습니다. +항상 인증 요청이 필요하므로, 모든 선택적 설정을 래핑하는 `authRequestOptionalConfig`가 제공됩니다. 자세한 내용은 [OIDC 인증 요청](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)을 참고하세요. 또한, 이 설정에 `nonce`가 없는 것을 볼 수 있습니다. `nonce`는 각 요청마다 고유해야 하므로, 코드 구현에서 생성하도록 했습니다. 걱정하지 않으셔도 됩니다! 앞서 언급한 `jwksUri`와 `issuer`도 `idTokenVerificationConfig`에 포함되어 있습니다. -표준 OIDC 프로토콜이 암시적 및 하이브리드 플로우를 모두 지원하는데, Logto 커넥터가 인가 플로우만 지원하는 이유가 궁금할 수 있습니다. 암시적 및 하이브리드 플로우는 인가 플로우보다 덜 안전한 것으로 판단되었습니다. Logto는 보안에 중점을 두고 있기 때문에, 사용자에게 가장 높은 수준의 보안을 제공하기 위해 인가 플로우만 지원합니다. 이는 약간 덜 편리할 수 있습니다. +표준 OIDC 프로토콜이 암시적(implicit) 및 하이브리드(hybrid) 플로우를 모두 지원하는데, 왜 Logto 커넥터는 인가 플로우만 지원하는지 궁금할 수 있습니다. 암시적 및 하이브리드 플로우는 인가 플로우보다 보안성이 떨어지는 것으로 판단되었습니다. Logto는 보안을 중시하기 때문에, 사용자에게 최고의 보안 수준을 제공하기 위해 약간의 불편함이 있더라도 인가 플로우만 지원합니다. -`responseType`과 `grantType`은 "Authorization Code" 플로우에서만 고정된 값일 수 있으므로, 우리는 이를 선택 사항으로 만들고 기본 값이 자동으로 채워지도록 했습니다. +`responseType`과 `grantType`은 "Authorization Code" 플로우에서만 고정 값이 될 수 있으므로, 선택 사항으로 두고 기본값이 자동으로 채워지도록 했습니다. :::note -모든 플로우 타입에 대해, 우리는 사용자 정의 매개변수를 넣을 수 있는 OPTIONAL `customConfig` 키를 제공했습니다. -각 소셜 아이덴티티 제공자는 OIDC 표준 프로토콜에 대한 자체 변형을 가질 수 있습니다. 원하는 소셜 아이덴티티 제공자가 OIDC 표준 프로토콜을 엄격히 준수한다면, `customConfig`에 대해 신경 쓸 필요가 없습니다. +모든 플로우 타입에 대해, 커스터마이즈 파라미터를 넣을 수 있도록 OPTIONAL `customConfig` 키를 제공합니다. +각 소셜 아이덴티티 제공자는 OIDC 표준 프로토콜에 대해 자체 변형을 가질 수 있습니다. 만약 원하는 소셜 아이덴티티 제공자가 OIDC 표준 프로토콜을 엄격히 준수한다면, `customConfig`는 신경 쓰지 않으셔도 됩니다. ::: @@ -82,4 +82,70 @@ _issuer_: 이는 IdP의 고유 식별자로, RP가 IdP로부터 받은 JWT를 | subject | string | False | | typ | string | False | -`IdTokenVerificationConfig`에 대한 자세한 내용은 [여기](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md)를 참조하세요. +`IdTokenVerificationConfig`에 대한 자세한 내용은 [여기](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md)를 참고하세요. + +## 일반 설정 \{#general-settings} + +다음은 아이덴티티 제공자와의 연결을 막지는 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다. + +### 소셜 버튼 이름 및 로고 \{#social-button-name-and-logo} + +로그인 페이지에 소셜 버튼을 표시하고 싶다면, 소셜 아이덴티티 제공자의 **이름**과 **로고**(다크 모드 및 라이트 모드)를 설정할 수 있습니다. 이를 통해 사용자가 소셜 로그인 옵션을 쉽게 인식할 수 있습니다. + +### 아이덴티티 제공자 이름 \{#identity-provider-name} + +각 소셜 커넥터는 사용자 아이덴티티를 구분하기 위해 고유한 아이덴티티 제공자 (IdP) 이름을 가집니다. 일반 커넥터는 고정된 IdP 이름을 사용하지만, 커스텀 커넥터는 고유한 값을 필요로 합니다. 자세한 내용은 [IdP 이름](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name)을 참고하세요. + +### 프로필 정보 동기화 \{#sync-profile-information} + +OIDC 커넥터에서는 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요: + +- **회원가입 시에만 동기화**: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다. +- **매 로그인 시마다 동기화**: 사용자가 로그인할 때마다 프로필 정보가 업데이트됩니다. + +### 타사 API 접근을 위한 토큰 저장 (선택 사항) \{#store-tokens-to-access-third-party-apis-optional} + +아이덴티티 제공자의 API에 접근하여 사용자 인가로 작업을 수행하려면 (소셜 로그인 또는 계정 연동을 통해), Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다. + +1. 위의 안내에 따라 **scope** 필드에 필요한 스코프를 추가하세요. +2. Logto OIDC 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 활성화하세요. Logto는 액세스 토큰을 Secret Vault에 안전하게 저장합니다. +3. **표준** OAuth/OIDC 아이덴티티 제공자의 경우, 리프레시 토큰 (Refresh token)을 얻으려면 반드시 `offline_access` 스코프를 포함해야 하며, 이를 통해 반복적인 사용자 동의 요청을 방지할 수 있습니다. + +:::warning +클라이언트 시크릿을 안전하게 보관하고, 절대 클라이언트 사이드 코드에 노출하지 마세요. 유출 시, 즉시 아이덴티티 제공자 앱 설정에서 새로 발급받으세요. +::: + +## OIDC 커넥터 활용하기 \{#utilize-the-oidc-connector} + +OIDC 커넥터를 생성하고 아이덴티티 제공자와 연결한 후, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요: + +### 소셜 로그인 버튼 활성화 \{#enable-social-sign-in-button} + +1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요. +2. **소셜 로그인** 섹션에서 OIDC 커넥터를 추가하여 사용자가 아이덴티티 제공자를 통해 인증 (Authentication)할 수 있도록 하세요. + +[소셜 로그인 경험](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in)에 대해 더 알아보세요. + +### 소셜 계정 연결 또는 연결 해제 \{#link-or-unlink-a-social-account} + +Account API를 사용하여 앱 내에 커스텀 계정 센터를 구축하고, 로그인한 사용자가 소셜 계정을 연결하거나 연결 해제할 수 있도록 하세요. [Account API 튜토리얼 따라하기](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +소셜 로그인을 활성화하지 않고, 계정 연동 및 API 접근만을 위해 OIDC 커넥터를 사용할 수도 있습니다. +::: + +### 아이덴티티 제공자 API 접근 및 작업 수행 \{#access-identity-provider-apis-and-perform-actions} + +애플리케이션은 Secret Vault에서 저장된 액세스 토큰을 가져와 아이덴티티 제공자의 API를 호출하고 백엔드 작업을 자동화할 수 있습니다. 구체적인 기능은 아이덴티티 제공자와 요청한 스코프에 따라 다릅니다. API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요. + +## 사용자의 소셜 아이덴티티 관리 \{#manage-user-s-social-identity} + +사용자가 소셜 계정을 연결한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다: + +1. Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다. +2. **소셜 연결**에서 아이덴티티 제공자 항목을 찾아 **관리**를 클릭하세요. +3. 이 페이지에서 관리자는 사용자의 소셜 연결을 관리하고, 소셜 계정에서 부여 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 상태를 점검할 수 있습니다. + +:::note +일부 아이덴티티 제공자의 액세스 토큰 응답에는 특정 스코프 정보가 포함되어 있지 않아, Logto가 사용자가 부여한 권한 목록을 직접 표시할 수 없습니다. 그러나 사용자가 인가 과정에서 요청된 스코프에 동의한 경우, 애플리케이션은 OIDC API 접근 시 해당 권한을 갖게 됩니다. +::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index 61779e63bf6..92e9abf5bdd 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: Google 생태계 내에서 사용자 접근을 통합하고 안전하게 관리합니다. + description: Google 생태계 내에서 사용자의 접근을 통합적이고 안전하게 관리합니다 (Unified and secure management of user access within the Google ecosystem). logoFilename: 'google.svg' tutorial_name: Google Workspace enterprise SSO tutorial_config_name: Google Cloud Platform @@ -16,22 +16,23 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -# Google Workspace 로 싱글 사인온 (SSO) 설정하세요 +# Google Workspace로 싱글 사인온 (SSO)을 설정하세요 -최소한의 구성 노력으로 이 커넥터는 Microsoft Entra ID 와의 통합을 통해 엔터프라이즈 SSO 를 가능하게 합니다. +최소한의 설정만으로, 이 커넥터를 통해 Microsoft Entra ID와 연동하여 엔터프라이즈 싱글 사인온 (SSO)을 구현할 수 있습니다. -## 1단계: Google Cloud Platform 에서 새 프로젝트 생성하기 \{#step-1-create-a-new-project-on-google-cloud-platform} +## 1단계: Google Cloud Platform에서 새 프로젝트 생성하기 \{#step-1-create-a-new-project-on-google-cloud-platform} -## 2단계: 애플리케이션을 위한 동의 화면 구성하기 \{#step-2-config-the-consent-screen-for-your-application} +## 2단계: 애플리케이션의 동의 화면(Consent screen) 구성하기 \{#step-2-config-the-consent-screen-for-your-application} -## 3단계: 새 OAuth 자격 증명 생성하기 \{#step-3-create-a-new-oauth-credential} +## 3단계: 새로운 OAuth 자격 증명 생성하기 \{#step-3-create-a-new-oauth-credential} @@ -43,6 +44,10 @@ import Step6 from './_step-6.mdx'; -## 6단계: 이메일 도메인 설정 및 SSO 커넥터 활성화하기 \{#step-6-set-email-domains-and-enable-the-sso-connector} +## 6단계: Google API에 접근하기 위한 토큰 저장 (선택 사항) \{#step-6-store-tokens-to-access-google-apis-optional} + +## 7단계: 이메일 도메인 설정 및 SSO 커넥터 활성화 \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index 29c146be172..de555e72405 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,20 +4,21 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -### 1단계: Google Cloud Platform 에서 새 프로젝트 생성 \{#step-1-create-a-new-project-on-google-cloud-platform} +### 1단계: Google Cloud Platform에서 새 프로젝트 생성하기 \{#step-1-create-a-new-project-on-google-cloud-platform} -### 2단계: 애플리케이션의 동의 화면 구성 \{#step-2-config-the-consent-screen-for-your-application} +### 2단계: 애플리케이션의 동의 화면 구성하기 \{#step-2-config-the-consent-screen-for-your-application} -### 3단계: 새 OAuth 자격 증명 생성 \{#step-3-create-a-new-oauth-credential} +### 3단계: 새로운 OAuth 자격 증명 생성하기 \{#step-3-create-a-new-oauth-credential} -### 4단계: 클라이언트 자격 증명으로 Logto 커넥터 설정 \{#step-4-set-up-logto-connector-with-the-client-credentials} +### 4단계: 클라이언트 자격 증명으로 Logto 커넥터 설정하기 \{#step-4-set-up-logto-connector-with-the-client-credentials} @@ -25,6 +26,10 @@ import Step6 from './_step-6.mdx'; -### 6단계: 이메일 도메인 설정 및 SSO 커넥터 활성화 \{#step-6-set-email-domains-and-enable-the-sso-connector} +### 6단계: Google API에 접근하기 위한 토큰 저장 (선택 사항) \{#step-6-store-tokens-to-access-google-apis-optional} + +### 7단계: 이메일 도메인 설정 및 SSO 커넥터 활성화 \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index 4836e6d572d..55463f5920b 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -`Scope` 필드를 사용하여 OAuth 요청에 추가적인 스코프를 추가하세요. 이를 통해 Google OAuth 서버로부터 더 많은 정보를 요청할 수 있습니다. 자세한 내용은 [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) 문서를 참조하세요. +스코프 (Scopes)는 애플리케이션이 사용자로부터 요청하는 권한 (Permissions)을 정의하며, 애플리케이션이 사용자의 Google Workspace 계정에서 접근할 수 있는 데이터를 제어합니다. Google 권한을 요청하려면 양쪽 모두에서 설정이 필요합니다: -사용자 정의 스코프 설정과 관계없이, Logto는 항상 `openid`, `profile`, `email` 스코프를 IdP에 전송합니다. 이는 Logto가 사용자의 아이덴티티 정보와 이메일 주소를 올바르게 가져올 수 있도록 하기 위함입니다. +**Google Cloud Console에서:** + +1. **APIs & Services > OAuth consent screen > Scopes**로 이동하세요. +2. **Add or Remove Scopes**를 클릭하고, 애플리케이션에 필요한 스코프만 선택하세요: + - 인증 (Authentication) (필수): + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - API 접근 (선택): 애플리케이션에 추가로 필요한 스코프를 추가하세요 (예: Drive, Calendar, YouTube). 사용 가능한 서비스를 찾으려면 [Google API Library](https://console.cloud.google.com/apis/library)를 둘러보세요. 애플리케이션이 기본 권한을 넘어 Google API에 접근해야 하는 경우, 먼저 Google API Library에서 사용할 특정 API(예: Google Drive API, Gmail API, Calendar API)를 활성화해야 합니다. +3. **Update**를 클릭하여 선택을 확인하세요. +4. **Save and Continue**를 클릭하여 변경 사항을 적용하세요. + +**Logto Google Workspace 커넥터에서:** + +1. Logto는 기본 사용자 아이덴티티 정보를 가져오기 위해 `openid`, `profile`, `email` 스코프를 자동으로 포함합니다. 기본 사용자 정보만 필요하다면 `Scopes` 필드를 비워두어도 됩니다. +2. Google에서 더 많은 데이터를 요청하려면 `Scopes` 필드에 추가 스코프(공백으로 구분)를 입력하세요. 전체 스코프 URL을 사용해야 하며, 예시: `https://www.googleapis.com/auth/calendar.readonly` + +:::tip +애플리케이션이 Google API에 접근하여 작업을 수행하기 위해 이러한 스코프를 요청하는 경우, Logto Google 커넥터에서 **Store tokens for persistent API access**를 반드시 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요. +::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index c40bef5a7fd..57ce84fac2d 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -Logto의 커넥터 `SSO 경험` 탭에서 조직의 `이메일 도메인`을 제공하세요. 이렇게 하면 해당 사용자들에게 SSO 커넥터가 인증 (Authentication) 방법으로 활성화됩니다. +[Google API](https://console.cloud.google.com/apis/library)에 접근하고 사용자 인가 (Authorization)로 작업을 수행하려면, Logto가 특정 API 스코프 (Scope)를 받아 토큰을 저장해야 합니다. -지정된 도메인의 이메일 주소를 가진 사용자는 SSO 커넥터를 유일한 인증 (Authentication) 방법으로 사용하도록 리디렉션됩니다. +1. Google Cloud Console의 OAuth 동의 화면 구성과 Logto Google 커넥터에 필요한 스코프 (Scope)를 추가하세요. +2. Logto Google 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 활성화하세요. Logto는 Google 액세스 토큰 (Access token)과 리프레시 토큰 (Refresh token)을 Secret Vault에 안전하게 저장합니다. +3. 리프레시 토큰 (Refresh token)이 반환되도록 하려면, Logto Google 커넥터에서 **오프라인 접근 (Offline Access)**을 활성화하세요. -Google Workspace SSO 커넥터에 대한 자세한 정보는 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect)를 확인하세요. +:::warning +Logto의 `Scope` 필드에 `offline_access`를 추가할 필요가 없습니다 — 추가하면 오류가 발생할 수 있습니다. Google은 오프라인 접근이 활성화되면 자동으로 `access_type=offline`을 사용합니다. +::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..a28c575a72e --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +Logto의 커넥터 `SSO 경험` 탭에서 조직의 `이메일 도메인`을 입력하세요. 이렇게 하면 해당 도메인을 가진 사용자들에게 SSO 커넥터가 인증 (Authentication) 방법으로 활성화됩니다. + +지정한 도메인의 이메일 주소를 가진 사용자는 SSO 커넥터만을 인증 (Authentication) 방법으로 사용하도록 리디렉션됩니다. + +Google Workspace SSO 커넥터에 대한 자세한 내용은 [Google OpenID 커넥터](https://developers.google.com/identity/openid-connect/openid-connect)를 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 4d86ad8ef6c..872f3dceafc 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -1,10 +1,10 @@ --- slug: /integrations/oidc-sso -sidebar_label: OIDC (Enterprise) +sidebar_label: OIDC (엔터프라이즈) sidebar_custom_props: - description: 웹 및 모바일 앱에서 아이덴티티 검증을 위한 OAuth 2.0 기반의 현대적인 프로토콜입니다. + description: 웹 및 모바일 앱에서 아이덴티티 검증을 위한 OAuth 2.0 기반의 최신 프로토콜입니다. logoFilename: 'oidc.svg' -tutorial_name: OIDC enterprise SSO +tutorial_name: OIDC 엔터프라이즈 SSO tutorial_config_name: IdP에서 OIDC 애플리케이션 --- @@ -13,10 +13,12 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; -# OpenID Connect (OIDC)로 싱글 사인온 (SSO) 설정하세요 +# OpenID Connect (OIDC)로 싱글 사인온 (SSO)을 설정하세요 -최소한의 구성 노력으로, 이 커넥터는 OIDC 기반 아이덴티티 제공자 (IdP)와의 통합을 허용합니다. +최소한의 설정만으로, 이 커넥터를 통해 모든 OIDC 기반 아이덴티티 제공자 (IdP)와 통합할 수 있습니다. @@ -28,6 +30,14 @@ import Step3 from './_step-3.mdx'; -## 3단계: 이메일 도메인 설정 및 SSO 커넥터 활성화하기 \{#step-3-set-email-domains-and-enable-the-sso-connector} +## 3단계: 스코프 구성 (선택 사항) \{#step-3-configure-scopes-optional} + +## 4단계: 타사 API에 접근하기 위한 토큰 저장 (선택 사항) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## 5단계: 이메일 도메인 설정 및 SSO 커넥터 활성화 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index 6ecb26008b5..5035fda6917 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,6 +1,8 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; ### 1단계: IdP에서 OIDC 애플리케이션 생성하기 \{#step-1-create-an-oidc-application-on-your-idp} @@ -10,6 +12,14 @@ import Step3 from './_step-3.mdx'; -### 3단계: 이메일 도메인 설정 및 SSO 커넥터 활성화하기 \{#step-3-set-email-domains-and-enable-the-sso-connector} +## 3단계: 스코프 구성하기 (선택 사항) \{#step-3-configure-scopes-optional} + +## 4단계: 타사 API에 접근하기 위한 토큰 저장하기 (선택 사항) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## 5단계: 이메일 도메인 설정 및 SSO 커넥터 활성화하기 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index ce1344d929b..c5ade0bf335 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -IdP 측에서 OIDC 애플리케이션을 성공적으로 생성한 후, IdP 구성을 Logto에 다시 제공해야 합니다. `Connection` 탭으로 이동하여 다음 구성을 입력하세요: +IdP 측에서 OIDC 애플리케이션을 성공적으로 생성한 후, 해당 IdP 설정 정보를 Logto에 다시 제공해야 합니다. `Connection` 탭으로 이동하여 다음 설정 정보를 입력하세요: -- **Client ID**: IdP에 의해 OIDC 애플리케이션에 할당된 고유 식별자입니다. 이 식별자는 OIDC 흐름 동안 Logto가 애플리케이션을 식별하고 인증하는 데 사용됩니다. -- **Client Secret**: Logto와 IdP 간에 공유되는 기밀 비밀입니다. 이 비밀은 OIDC 애플리케이션을 인증하고 Logto와 IdP 간의 통신을 보호하는 데 사용됩니다. -- **발급자 (Issuer)**: OIDC 아이덴티티 제공자가 위치한 장소를 지정하는 IdP의 고유 식별자인 발급자 URL입니다. 이는 Logto가 필요한 엔드포인트를 발견하는 데 도움을 주는 OIDC 구성의 중요한 부분입니다. - 구성 과정을 쉽게 하기 위해 Logto는 제공한 발급자를 사용하여 IdP의 OIDC 발견 엔드포인트에 호출을 하여 필요한 OIDC 엔드포인트와 구성을 자동으로 가져옵니다. 발급자 엔드포인트가 유효하고 정확하게 구성되어 Logto가 필요한 정보를 올바르게 가져올 수 있도록 하는 것이 중요합니다. - 요청이 성공적으로 완료되면 발급자 섹션에서 구문 분석된 IdP 구성을 볼 수 있어야 합니다. -- **스코프 (Scope)**: OIDC 인증 과정에서 Logto가 요청하는 원하는 권한 또는 접근 수준을 정의하는 공백으로 구분된 문자열 목록입니다. 스코프 매개변수를 통해 Logto가 IdP로부터 어떤 정보와 접근을 요청하는지 지정할 수 있습니다. - 스코프 매개변수는 선택 사항입니다. 사용자 정의 스코프 설정과 관계없이, Logto는 항상 `openid`, `profile`, `email` 스코프를 IdP에 전송합니다. - 이는 Logto가 IdP로부터 사용자의 아이덴티티 정보와 이메일 주소를 올바르게 가져올 수 있도록 하기 위함입니다. IdP로부터 더 많은 정보를 요청하기 위해 스코프 매개변수에 추가적인 스코프를 추가할 수 있습니다. +- **Client ID**: IdP에서 OIDC 애플리케이션에 할당한 고유 식별자입니다. 이 식별자는 Logto가 OIDC 플로우 중 애플리케이션을 식별하고 인증하는 데 사용됩니다. +- **Client Secret**: Logto와 IdP 간에 공유되는 비밀 값입니다. 이 비밀 값은 OIDC 애플리케이션을 인증하고 Logto와 IdP 간의 통신을 보호하는 데 사용됩니다. +- **발급자 (Issuer)**: 발급자 URL로, IdP의 고유 식별자이며 OIDC 아이덴티티 제공자 (IdP)가 위치한 곳을 지정합니다. 이는 OIDC 설정에서 매우 중요한 부분으로, Logto가 필요한 엔드포인트를 찾는 데 도움을 줍니다. + 설정 과정을 더 쉽게 하기 위해 Logto는 필요한 OIDC 엔드포인트와 설정 정보를 자동으로 가져옵니다. 이는 입력한 발급자 (Issuer)를 활용하여 IdP의 OIDC 디스커버리 엔드포인트에 요청을 보내는 방식으로 이루어집니다. Logto가 필요한 정보를 올바르게 가져올 수 있도록 발급자 (Issuer) 엔드포인트가 유효하고 정확하게 설정되어 있는지 반드시 확인해야 합니다. + 요청이 성공적으로 완료되면, 발급자 (Issuers) 섹션에서 파싱된 IdP 설정 정보를 확인할 수 있습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index 75a091be8bd..6a6c8759b9e 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -Logto의 커넥터 `SSO 경험` 탭에서 조직의 `이메일 도메인`을 제공하세요. 이렇게 하면 해당 사용자들에게 SSO 커넥터가 인증 (Authentication) 방법으로 활성화됩니다. +스코프 (Scopes)는 애플리케이션이 사용자로부터 요청하는 권한 (Permissions)을 정의하며, 엔터프라이즈 계정에서 애플리케이션이 접근할 수 있는 데이터를 제어합니다. -지정된 도메인의 이메일 주소를 가진 사용자는 SSO 커넥터를 유일한 인증 (Authentication) 방법으로 사용하도록 리디렉션됩니다. +스코프 설정은 양쪽에서 구성이 필요합니다: + +1. **아이덴티티 제공자 (IdP)**: IdP 콘솔에서 인가 (Authorization)에 허용할 권한 (Permissions)을 구성하세요. + - 일부 IdP는 모든 공개 스코프 (Scopes)를 기본적으로 활성화합니다 (별도의 조치 필요 없음) + - 다른 IdP는 명시적으로 권한 (Permissions)을 부여해야 합니다 +2. **Logto 엔터프라이즈 커넥터**: Logto OIDC 엔터프라이즈 커넥터 설정 > `Scopes` 필드에서 인증 (Authentication) 중 요청할 스코프 (Scopes)를 지정하세요. + - Logto는 기본 사용자 아이덴티티 정보를 가져오기 위해 항상 `openid`, `profile`, `email` 스코프 (Scopes)를 포함합니다. 이는 사용자 지정 스코프 설정과 관계없이 적용됩니다. + - 추가 정보를 IdP로부터 요청하려면, 공백으로 구분하여 추가 스코프 (Scopes)를 입력할 수 있습니다. + +:::tip +애플리케이션이 이러한 스코프 (Scopes)를 사용하여 API에 접근해야 하는 경우, Logto 엔터프라이즈 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 반드시 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요. +::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..267e8efe2ec --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +아이덴티티 제공자 (IdP)의 API에 접근하고 사용자 인가 (Authorization)로 작업을 수행하려면, Logto가 특정 API 스코프 (Scope)를 받아 토큰을 저장해야 합니다. + +1. 위의 안내에 따라 **scope** 필드에 필요한 스코프 (Scope)를 추가하세요. +2. Logto OIDC 엔터프라이즈 커넥터에서 **지속적인 API 접근을 위한 토큰 저장**을 활성화하세요. Logto는 액세스 토큰 (Access token)을 시크릿 볼트에 안전하게 저장합니다. +3. **표준** OIDC 아이덴티티 제공자 (IdP)의 경우, 리프레시 토큰 (Refresh token)을 얻기 위해 반드시 `offline_access` 스코프 (Scope)를 포함해야 하며, 이를 통해 반복적인 사용자 동의 화면 (Consent screen) 표시를 방지할 수 있습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..8f62a92fafd --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +Logto의 커넥터 `SSO 경험` 탭에서 조직의 `이메일 도메인`을 입력하세요. 이렇게 하면 해당 도메인의 사용자들에게 SSO 커넥터가 인증 (Authentication) 방법으로 활성화됩니다. + +지정한 도메인에 속한 이메일 주소를 가진 사용자는 SSO 커넥터만을 인증 (Authentication) 방법으로 사용하도록 리디렉션됩니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index 0b625c40d76..b63ebe6dfbb 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -4,38 +4,42 @@ sidebar_position: 2 # 배포 및 구성 -이전 기사에서는 [Logto를 빠르게 시작하는 방법](/logto-oss/get-started-with-oss)의 기본 사항을 다루었습니다. 이 기사는 Logto를 프로덕션 환경에 배포하기 위한 모범 사례와 자세한 구성 단계를 중점적으로 다룹니다. +이전 글에서는 [Logto 빠르게 시작하기](/logto-oss/get-started-with-oss)의 기본 사항을 다루었습니다. 이 글에서는 프로덕션 환경에서 Logto를 배포하기 위한 모범 사례와 상세한 구성 단계에 대해 더 깊이 다룹니다. ## 환경 변수 \{#environment-variables} -우리는 데모 (`docker-compose.yml`)에서 생성된 환경 변수 프리셋을 사용합니다. 이를 자신의 것으로 교체하고 여러 Logto 인스턴스 간에 일관성을 유지해야 합니다. +데모(`docker-compose.yml`)에서는 미리 생성된 환경 변수 프리셋을 사용합니다. 프로덕션 환경에서는 반드시 본인만의 값으로 교체하고, 여러 Logto 인스턴스 간에 일관성을 유지해야 합니다. -환경 변수를 직접 설정하거나 Logto 프로젝트 루트에 `.env` 파일을 넣을 수 있습니다. Docker로 테스트 중이라면, `/etc/logto`에 생성된 이미지의 `.env`를 확인하세요. +환경 변수는 직접 설정하거나, Logto 프로젝트 루트에 `.env` 파일을 넣어 설정할 수 있습니다. Docker로 테스트하는 경우, 이미지의 `/etc/logto`에 생성된 `.env`를 확인하세요. -### 필수 요소 \{#essentials} +### 필수 항목 \{#essentials} -- `DB_URL` Logto 데이터베이스를 위한 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6). -- `PORT` Logto가 수신하는 포트. 기본값 `3001`. -- `ENDPOINT` 프로덕션을 위해 사용자 지정 도메인으로 URL을 지정할 수 있습니다 (예: `ENDPOINT=https://logto.domain.com`). 이는 [OIDC 발급자 식별자](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier)의 값에도 영향을 미칩니다. +- `DB_URL` Logto 데이터베이스용 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6). +- `PORT` Logto가 리스닝하는 포트. 기본값은 `3001`. +- `ENDPOINT` 프로덕션 환경에서 커스텀 도메인으로 URL을 지정할 수 있습니다 (예: `ENDPOINT=https://logto.domain.com`). 이는 [OIDC 발급자 식별자 (Issuer Identifier)](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 값에도 영향을 줍니다. **관리 콘솔 활성화** -- `ADMIN_PORT` Logto 관리 콘솔이 수신하는 포트. 기본값 `3002`. -- `ADMIN_ENDPOINT` 프로덕션을 위해 사용자 지정 도메인으로 URL을 지정할 수 있습니다 (예: `ADMIN_ENDPOINT=https://admin.domain.com`). 이는 관리 콘솔 리디렉션 URI의 값에도 영향을 미칩니다. +- `ADMIN_PORT` Logto 관리 콘솔이 리스닝하는 포트. 기본값은 `3002`. +- `ADMIN_ENDPOINT` 프로덕션 환경에서 커스텀 도메인으로 URL을 지정할 수 있습니다 (예: `ADMIN_ENDPOINT=https://admin.domain.com`). 이는 관리 콘솔 리디렉션 URI 값에도 영향을 줍니다. **관리 콘솔 비활성화** -- `ADMIN_DISABLE_LOCALHOST` 관리 콘솔의 포트를 닫으려면 `1` 또는 `true`로 설정하세요. `ADMIN_ENDPOINT`가 설정되지 않은 경우, 관리 콘솔을 완전히 비활성화합니다. +- `ADMIN_DISABLE_LOCALHOST` 값을 `1` 또는 `true`로 설정하면 관리 콘솔 포트가 닫힙니다. `ADMIN_ENDPOINT`가 설정되지 않은 경우, 관리 콘솔이 완전히 비활성화됩니다. -환경 변수에 대한 자세한 내용은 [구성](/concepts/core-service/configuration/)을 참조하세요. +환경 변수에 대한 자세한 내용은 [구성](/concepts/core-service/configuration/)을 참고하세요. + +**시크릿 볼트 활성화** + +- [시크릿 볼트](/secret-vault)를 사용하려면, `SECRET_VAULT_KEK`에 Key Encryption Key (KEK)의 base64 인코딩 문자열을 설정해야 합니다. 이는 시크릿 볼트 내 Data Encryption Key (DEK)를 암호화하는 데 사용됩니다. AES-256 (32바이트)을 권장합니다. 예시: `crypto.randomBytes(32).toString('base64')`. ### HTTPS \{#https} -Node.js를 사용하여 HTTPS를 직접 제공하거나 Node.js 앞에 HTTPS 프록시 / 밸런서를 설정할 수 있습니다. 자세한 내용은 [HTTPS 활성화](/concepts/core-service/configuration/#enabling-https)를 참조하세요. +Node.js에서 직접 HTTPS를 제공하거나, Node.js 앞단에 HTTPS 프록시 / 로드 밸런서를 설정할 수 있습니다. 자세한 내용은 [HTTPS 활성화](/concepts/core-service/configuration/#enabling-https)를 참고하세요. ### 리버스 프록시 \{#reverse-proxy} -서버에서 Nginx 또는 Apache와 같은 리버스 프록시를 사용하려면, 프록시 패스 설정에서 3001 및 3002 포트를 별도로 매핑해야 합니다. Nginx를 사용한다고 가정하고, Logto 인증 엔드포인트가 포트 3001에서 실행 중이며, Logto 관리 콘솔이 포트 3002에서 실행 중이라면, nginx.conf에 다음 구성을 추가하세요: +서버에서 리버스 프록시(예: Nginx, Apache)를 사용하려면, 프록시 패스 설정에서 3001 및 3002 포트를 각각 매핑해야 합니다. Nginx를 사용하는 경우, Logto 인증 엔드포인트는 3001 포트, Logto 관리 콘솔은 3002 포트에서 실행된다고 가정하고, nginx.conf에 다음 설정을 추가하세요: ``` server { @@ -58,7 +62,7 @@ server { } ``` -그런 다음 관리 콘솔에 대한 유사한 구성을 추가하세요: +관리 콘솔에도 유사한 설정을 추가하세요: ``` server { @@ -81,23 +85,23 @@ server { } ``` -최신 변경 사항을 반영하기 위해 Nginx 구성을 다시 로드하세요: +Nginx 설정을 다시 불러와 최신 변경 사항을 반영하세요: ``` nginx -s reload ``` -모든 설정이 완료되었습니다. 브라우저를 열고 `https://admin.your-domain.com`을 방문하면 Logto 환영 페이지를 볼 수 있습니다. +이제 준비가 완료되었습니다. 브라우저를 열고 `https://admin.your-domain.com`에 접속하면 Logto 환영 페이지를 볼 수 있습니다. ## 컨테이너화 \{#containerization} -프로덕션을 위해 Docker를 사용하여 Logto를 컨테이너화할 수 있습니다. 프로젝트의 루트 디렉토리에서 Dockerfile을 찾을 수 있습니다. Logto의 여러 인스턴스를 실행하려면, 예를 들어 Kubernetes 클러스터에 Logto를 배포하려면 추가적인 단계가 필요합니다. +프로덕션 환경에서는 Docker를 사용해 Logto를 컨테이너화할 수 있습니다. 프로젝트 루트 디렉터리에서 Dockerfile을 찾을 수 있습니다. Logto 인스턴스를 여러 개 실행하려면, 예를 들어 Kubernetes 클러스터에 배포하려면 추가로 수행해야 할 작업이 있습니다. ### 공유 커넥터 폴더 \{#shared-connectors-folder} -기본적으로 Logto는 `core` 폴더의 루트 디렉토리에 `connectors` 폴더를 생성합니다. 여러 Logto 인스턴스 간에 폴더를 공유하는 것을 권장합니다. `packages/core/connectors` 폴더를 컨테이너에 마운트하고 `npm run cli connector add -- --official`을 실행하여 커넥터를 배포해야 합니다. +기본적으로 Logto는 `core` 폴더의 루트에 `connectors` 폴더를 생성합니다. 여러 Logto 인스턴스 간에 이 폴더를 공유하는 것을 권장합니다. 컨테이너에 `packages/core/connectors` 폴더를 마운트하고, `npm run cli connector add -- --official` 명령어로 커넥터를 배포하세요. -Kubernetes에 대한 최소 예제 `배포`가 있습니다: +Kubernetes용 최소 예시 `deployment`는 다음과 같습니다: ```yaml apiVersion: extensions/v1beta1 @@ -130,21 +134,21 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -이 예제에서는 빈 디렉토리를 볼륨으로 생성하고 이를 컨테이너에 마운트합니다. 그런 다음 초기 컨테이너에서 `npm run cli connector add -- --official`을 실행하여 커넥터를 다운로드합니다. 마지막으로, 모든 컨테이너는 이미 내부에 있는 공식 커넥터와 함께 동일한 커넥터 폴더를 공유하게 됩니다. +이 예시에서는 빈 디렉터리를 볼륨으로 생성하여 컨테이너에 마운트합니다. 그리고 init 컨테이너에서 `npm run cli connector add -- --official` 명령어를 실행해 커넥터를 다운로드합니다. 마지막으로, 모든 컨테이너가 공식 커넥터가 포함된 동일한 커넥터 폴더를 공유하게 됩니다. :::note -이것은 예제 yaml입니다. Logto를 실행하려면 환경 변수를 적절히 설정해야 합니다. +이것은 예시 yaml입니다. Logto를 실행하려면 환경 변수도 올바르게 설정해야 합니다. ::: -프로덕션에서는 "빈 디렉토리" 볼륨을 영구 볼륨으로 교체하고, "초기" 작업을 자신의 방식으로 수행할 수 있습니다. 당신이 무엇을 하고 있는지 알고 있다면! +프로덕션 환경에서는 "empty dir" 볼륨을 영구 볼륨으로 교체하고, "init" 작업도 직접 원하는 방식으로 수행할 수 있습니다. 여러분이 무엇을 하는지 알고 있다면 가능합니다! ### 데이터베이스 변경 \{#database-alteration} -커넥터와 유사하게, 데이터베이스 변경은 단일 인스턴스에서 실행해야 합니다. 작업을 사용하여 변경 스크립트를 실행할 수 있습니다. +커넥터와 마찬가지로, 데이터베이스 변경 작업도 단일 인스턴스에서 실행해야 합니다. 작업(Job)을 사용해 변경 스크립트를 실행할 수 있습니다. -비상호작용으로 변경이 실행될 때 `CI=true` 환경 변수가 필요합니다. +비상호작용 환경에서 변경 작업을 실행할 때는 `CI=true` 환경 변수가 필요합니다. ```yaml apiVersion: batch/v1 @@ -171,4 +175,4 @@ spec: restartPolicy: Never ``` -변경 명령에 대한 자세한 내용은 [데이터베이스 변경](/logto-oss/using-cli/database-alteration/)을 참조하세요. +변경 명령어에 대한 자세한 내용은 [데이터베이스 변경](/logto-oss/using-cli/database-alteration/)을 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..8025e62998a --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# 시크릿 볼트 (Secret Vault) + +Logto의 시크릿 볼트 (Secret Vault)는 액세스 토큰 (Access token), API 키, 패스코드 또는 보호가 필요한 기타 기밀 정보를 안전하게 저장하도록 설계되었습니다. 이러한 시크릿은 종종 사용자를 대신하여 타사 서비스에 접근하는 데 사용되므로, 안전한 저장이 필수적입니다. + +## 암호화 방식 \{#encryption-scheme} + +민감한 데이터를 보호하기 위해, 시크릿 볼트는 **데이터 암호화 키 (DEK)**와 **키 암호화 키 (KEK)** 기반의 강력한 암호화 방식을 사용합니다. + +- **시크릿별 암호화:** 각 시크릿은 고유한 DEK로 암호화되어, 하나의 키가 유출되더라도 다른 시크릿은 안전하게 보호됩니다. +- **키 래핑:** DEK 자체는 KEK로 암호화(또는 "래핑")되며, KEK는 시스템에 의해 안전하게 관리 및 저장됩니다. +- **계층적 보안:** 이 2단계 방식은 시스템의 일부가 침해되더라도, 공격자가 DEK와 KEK 모두 없이는 시크릿에 접근할 수 없도록 보장합니다. +- **노출 최소화:** 시크릿은 반드시 필요할 때만 복호화되어, 우발적 노출 위험을 줄이고 민감한 데이터 처리에 대한 모범 사례를 따릅니다. + +이 계층적 암호화 모델은 사용자의 가장 민감한 자격 증명 및 토큰을 강력하게 보호하면서도, 필요할 때 안전하게 접근할 수 있도록 합니다. + +## 시크릿 유형 \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +현재, 연동 토큰 세트 (Federated token set)가 기본적으로 지원되는 유일한 시크릿 유형입니다. 하지만 시크릿 볼트 (Secret Vault)는 모든 종류의 민감한 정보를 저장할 수 있도록 설계되었습니다. 추가적인 시크릿 유형 지원이 필요하다면, [문의해 주세요](https://logto.io/contact) — 언제든 도와드릴 준비가 되어 있습니다. +::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..344e76481f0 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: 연동 토큰 세트 (Federated token set) +sidebar_label: 연동 토큰 세트 (Federated token set) +--- + +import Availability from '@components/Availability'; + + + +연동 토큰 세트 (Federated token set)는 Logto의 Secret Vault에 저장되는 비밀 유형으로, 연동된 서드파티 아이덴티티 제공자가 발급한 액세스 토큰 (Access token) 및 리프레시 토큰 (Refresh token)을 안전하게 관리하는 데 사용됩니다. 사용자가 소셜 또는 엔터프라이즈 싱글 사인온 (SSO) 커넥터를 통해 인증 (Authentication)할 때, Logto는 발급된 토큰을 금고에 저장합니다. 이러한 토큰은 이후 재인증 없이 사용자를 대신하여 서드파티 API에 접근하기 위해 조회할 수 있습니다. + +## 연동 토큰 저장 활성화 \{#enable-federated-token-storage} + +### 소셜 커넥터 \{#social-connectors} + +:::Info +이 기능은 토큰 저장을 지원하는 커넥터에서만 사용할 수 있습니다. 현재 지원되는 커넥터는 다음과 같습니다: [GitHub](/integrations/github), [Google](/integrations/google), [Facebook](/integrations/facebook), [Standard OAuth 2.0](/integrations/oauth2), [Standard OIDC](/integrations/oidc). 추가 커넥터 지원은 점진적으로 제공될 예정입니다. +::: + +1. 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요. +2. 연동 토큰 저장을 활성화하려는 소셜 커넥터를 선택하세요. +3. "설정" 페이지에서 **지속적인 API 접근을 위한 토큰 저장** 옵션을 활성화하세요. + +### 엔터프라이즈 SSO 커넥터 \{#enterprise-sso-connectors} + +:::Info +토큰 저장은 모든 OIDC 엔터프라이즈 커넥터에서 사용할 수 있습니다. +::: + +1. 콘솔 > 엔터프라이즈 SSO로 이동하세요. +2. 연동 토큰 저장을 활성화하려는 엔터프라이즈 SSO 커넥터를 선택하세요. +3. "SSO 경험" 탭에서 **지속적인 API 접근을 위한 토큰 저장** 옵션을 활성화하세요. + +변경 사항을 반드시 저장하세요. + +## 토큰 저장 \{#token-storage} + +연동 토큰 저장이 활성화되면, 사용자가 소셜 또는 엔터프라이즈 SSO 커넥터를 통해 인증할 때마다 Logto는 연동된 아이덴티티 제공자가 발급한 액세스 토큰 (Access token) 및 리프레시 토큰 (Refresh token)을 자동으로 저장합니다. 여기에는 다음이 포함됩니다: + +- [소셜 로그인 및 회원가입](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [엔터프라이즈 SSO 로그인 및 회원가입](/end-user-flows/enterprise-sso) +- [Account API를 통한 소셜 계정 연결](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +저장된 토큰은 사용자의 소셜 또는 엔터프라이즈 SSO 아이덴티티에 연결되어, 재인증 없이 나중에 API 접근을 위해 토큰을 조회할 수 있습니다. + +### 토큰 저장 상태 확인 \{#checking-token-storage-status} + +Logto 콘솔에서 사용자의 연동 토큰 저장 상태를 확인할 수 있습니다: + +1. 콘솔 > 사용자로 이동하세요. +2. 확인하려는 사용자를 클릭하세요. 해당 사용자의 상세 페이지로 이동합니다. +3. **연결** 섹션까지 스크롤하세요. 이 영역에는 사용자와 연결된 모든 소셜 및 엔터프라이즈 SSO 연결이 나열됩니다. +4. 각 연결 항목에는 해당 연결에 대해 토큰이 저장되어 있는지 표시하는 토큰 상태 레이블이 있습니다. +5. 연결 항목을 클릭하면 저장된 액세스 토큰 (Access token) 메타데이터 및 리프레시 토큰 (Refresh token) 사용 가능 여부(가능한 경우)를 포함한 자세한 정보를 볼 수 있습니다. + +또한 관리 API를 통해 사용자 서드파티 아이덴티티 및 토큰 저장 상태를 확인할 수 있습니다: + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`: 지정한 커넥터 타겟(예: `github`, `google` 등)으로 연결된 사용자의 소셜 아이덴티티 및 토큰 저장 상태를 조회합니다. +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`: 지정한 SSO 커넥터 ID로 연결된 사용자의 엔터프라이즈 SSO 아이덴티티 및 토큰 저장 상태를 조회합니다. + +### 토큰 저장 상태 \{#token-storage-status} + +- **활성(Active)**: 액세스 토큰 (Access token)이 저장되어 있고 활성 상태입니다. +- **만료(Expired)**: 액세스 토큰 (Access token)이 저장되어 있지만 만료되었습니다. 리프레시 토큰 (Refresh token)이 있으면 새 액세스 토큰을 얻는 데 사용할 수 있습니다. +- **비활성(Inactive)**: 이 연결에 대해 저장된 액세스 토큰 (Access token)이 없습니다. 사용자가 이 연결을 통해 인증하지 않았거나 토큰 저장이 삭제된 경우 발생할 수 있습니다. +- **해당 없음(Not applicable)**: 해당 커넥터가 토큰 저장을 지원하지 않습니다. + +### 토큰 메타데이터 \{#token-metadata} + +데이터 무결성과 보안을 위해, 모든 토큰은 Secret Vault에 저장되기 전에 암호화됩니다. 실제 토큰 값은 적절한 인가 (Authorization)를 받은 최종 사용자만 접근할 수 있습니다. 개발자는 민감한 내용을 노출하지 않고 저장된 토큰의 상태를 파악하기 위해 토큰 세트 메타데이터만 조회할 수 있습니다. + +- `createdAt`: 연결이 처음 생성되고 토큰 세트가 Secret Vault에 최초로 저장된 시각입니다. +- `updatedAt`: 토큰 세트가 마지막으로 업데이트된 시각입니다. + - 리프레시 토큰 (Refresh token)이 없으면 이 값은 **createdAt**과 동일합니다. + - 리프레시 토큰이 있으면, 이 값은 액세스 토큰이 가장 최근에 갱신된 시각을 반영합니다. +- `hasRefreshToken`: 리프레시 토큰 (Refresh token) 사용 가능 여부를 나타냅니다. + 커넥터가 오프라인 접근을 지원하고 인가 요청이 적절히 구성된 경우, Logto는 아이덴티티 제공자가 액세스 토큰과 함께 리프레시 토큰을 발급할 때 이를 저장합니다. + 액세스 토큰이 만료되고 유효한 리프레시 토큰이 존재하면, 사용자가 연결된 제공자에 접근을 요청할 때마다 Logto는 저장된 리프레시 토큰을 사용해 자동으로 새 액세스 토큰을 얻으려고 시도합니다. +- `expiresAt`: 액세스 토큰 (Access token)의 예상 만료 시각(초 단위)입니다. + 이는 아이덴티티 제공자의 토큰 엔드포인트에서 반환된 `expires_in` 값을 기반으로 계산됩니다. (이 필드는 제공자가 토큰 응답에 `expires_in`을 포함할 때만 제공됩니다.) +- `scope`: 액세스 토큰 (Access token)의 스코프로, 아이덴티티 제공자가 부여한 권한 (Permission)을 나타냅니다. + 저장된 액세스 토큰으로 어떤 작업을 수행할 수 있는지 이해하는 데 유용합니다. (이 필드는 제공자가 토큰 응답에 `scope`를 포함할 때만 제공됩니다.) +- `tokenType`: 액세스 토큰 (Access token)의 유형으로, 일반적으로 "Bearer"입니다. + (이 필드는 제공자가 토큰 응답에 `token_type`을 포함할 때만 제공됩니다.) + +## 토큰 조회 \{#token-retrieval} + +토큰 저장이 활성화되고 토큰이 Logto의 Secret Vault에 안전하게 저장되면, 최종 사용자는 Logto의 [User Account API](/end-user-flows/account-settings/by-account-api)를 통합하여 클라이언트 애플리케이션에서 서드파티 액세스 토큰을 조회할 수 있습니다. + +- `GET /my-account/identities/:target/access-token`: 커넥터 타겟(예: github, google)을 지정하여 소셜 아이덴티티의 액세스 토큰을 조회합니다. + +- `GET /my-account/sso-identities/:connectorId/access-token`: 커넥터 ID를 지정하여 엔터프라이즈 SSO 아이덴티티의 액세스 토큰을 조회합니다. + +:::info +Logto에서 발급한 액세스 토큰 (Access token)을 사용하여 [Account API 활성화](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) 및 [Account API 접근](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) 방법을 알아보세요. +::: + +### 토큰 회전(Token rotation) \{#token-rotation} + +토큰 조회 엔드포인트는 다음과 같이 응답합니다: + +- `200` OK: 액세스 토큰 (Access token)이 성공적으로 조회되었고 여전히 유효한 경우. +- `404` Not Found: 지정한 타겟 또는 커넥터 ID와 연결된 소셜 또는 엔터프라이즈 SSO 아이덴티티가 없거나, 액세스 토큰이 저장되어 있지 않은 경우. +- `401` Unauthorized: 액세스 토큰 (Access token)이 만료된 경우. + +액세스 토큰이 만료되었고 리프레시 토큰 (Refresh token)이 있는 경우, Logto는 자동으로 액세스 토큰을 갱신하여 응답에 새 액세스 토큰을 반환합니다. Secret Vault의 토큰 저장소도 새 액세스 토큰과 메타데이터로 업데이트됩니다. + +## 토큰 저장 삭제 \{#token-storage-deletion} + +연동 토큰 저장은 각 사용자의 소셜 또는 엔터프라이즈 SSO 연결과 직접적으로 연결되어 있습니다. 즉, 다음과 같은 경우 저장된 토큰 세트가 자동으로 삭제됩니다: + +- 연결된 소셜 또는 엔터프라이즈 SSO 아이덴티티가 사용자 계정에서 제거된 경우. +- 사용자 계정이 테넌트에서 삭제된 경우. +- 소셜 또는 엔터프라이즈 SSO 커넥터가 테넌트에서 삭제된 경우. + +### 토큰 폐기(Revoking tokens) \{#revoking-tokens} + +사용자의 서드파티 토큰 세트를 수동으로 삭제하여 접근을 폐기할 수도 있습니다: + +- 콘솔에서: + 사용자 아이덴티티 상세 페이지로 이동하세요. **액세스 토큰 (Access token)** 섹션(토큰 저장이 가능한 경우)까지 스크롤한 후, 섹션 끝에 있는 **토큰 삭제** 버튼을 클릭하세요. +- 관리 API를 통해: + - `DELETE /api/secret/:id`: 사용자 아이덴티티 상세 정보에서 얻을 수 있는 ID로 특정 비밀을 삭제합니다. + +토큰 세트를 폐기하면 사용자는 서드파티 API에 다시 접근하기 전에 서드파티 제공자와 재인증해야 새 액세스 토큰을 얻을 수 있습니다. + +## 재인증 및 토큰 갱신 \{#reauthentication-and-token-renewal} + +저장된 액세스 토큰이 만료되었거나 애플리케이션에서 추가 API 스코프를 요청해야 하는 경우, 최종 사용자는 서드파티 제공자와 재인증하여 새로운 액세스 토큰을 얻을 수 있습니다—Logto에 다시 로그인할 필요 없이 가능합니다. +이는 Logto의 [Social Verification API](https://openapi.logto.io/operation/operation-createverificationbysocial)를 통해 구현할 수 있으며, 사용자가 연동 소셜 인가 플로우를 재시작하고 저장된 토큰 세트를 업데이트할 수 있습니다. + +:::note +연동 인가 재시작은 현재 소셜 커넥터에 한정되어 있습니다. +엔터프라이즈 SSO 커넥터의 경우, 재인증 및 토큰 갱신을 위해 사용자가 Logto 인증 (Authentication) 플로우 전체를 다시 시작해야 하며, 로그인 이후 엔터프라이즈 SSO 제공자와의 직접 재인가 (Reauthorization)는 현재 지원되지 않습니다. +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as 사용자 + participant Logto as Logto + participant Provider as 서드파티 제공자 + + User->>Logto: post /api/verification/social + Logto->>User: 서드파티 제공자로 리디렉션 + User->>Provider: 인증 및 인가 + Provider->>User: 인가 코드와 함께 리디렉션 + User->>Logto: post /api/verification/social/verify (인가 코드 포함) + Logto->>User: 소셜 인증 ID 반환 + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. 사용자가 `POST /api/verification/social` 엔드포인트를 호출하여 소셜 인증 요청을 시작합니다. 사용자는 서드파티 제공자로부터 추가 권한 (Permission)을 요청하기 위해 커스텀 스코프를 지정할 수 있습니다. + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**: Logto에서 발급한 사용자의 액세스 토큰 (Access token). + - **connectorId**: Logto의 소셜 커넥터 ID. + - **redirectUri**: 인증 후 사용자를 애플리케이션으로 리디렉션할 URI. 이 URI를 제공자의 애플리케이션 설정에 등록해야 합니다. + - **scope**: (선택 사항) 서드파티 제공자로부터 추가 권한 (Permission)을 요청할 커스텀 스코프. 지정하지 않으면 커넥터에 구성된 기본 스코프가 사용됩니다. + +2. Logto는 새로운 소셜 인증 레코드를 생성하고, 인증을 위해 사용자를 서드파티 제공자로 리디렉션할 인가 URL과 함께 소셜 인증 ID를 반환합니다. + + 응답 예시는 다음과 같습니다: + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. 사용자를 인가 URL로 리디렉션하세요. 사용자는 서드파티 제공자와 인증 및 권한 부여를 진행합니다. + +4. 서드파티 제공자는 인가 코드를 포함하여 사용자를 클라이언트 애플리케이션으로 리디렉션합니다. + +5. 인가 콜백을 처리하여 인가 코드를 Logto의 인증 엔드포인트로 전달하세요: + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**: Logto에서 발급한 사용자의 액세스 토큰 (Access token). + - **verificationRecordId**: 이전 단계에서 반환된 소셜 인증 ID. + - **connectorData**: 콜백 시 서드파티 제공자가 반환한 인가 코드 및 기타 데이터. + + :::note + CSRF 공격을 방지하기 위해 반드시 `state` 파라미터를 검증하세요. + ::: + +6. Logto는 인가 코드를 검증하고, 서드파티 제공자로부터 새 액세스 토큰 (Access token) 및 리프레시 토큰 (Refresh token)을 교환한 후, 응답에 소셜 인증 ID를 반환합니다. + +7. 마지막으로, 소셜 인증 ID를 사용하여 `PATCH /my-account/identities/:target/access-token` 엔드포인트를 호출해 사용자의 토큰 저장소를 업데이트하세요: + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**: Logto에서 발급한 사용자의 액세스 토큰 (Access token). + - **socialVerificationId**: 이전 단계에서 반환된 소셜 인증 레코드 ID. + + 이 과정을 통해 Logto의 Secret Vault에 사용자의 토큰 세트가 새 액세스 토큰 및 리프레시 토큰으로 업데이트되어, 사용자는 Logto에 다시 로그인하지 않고도 서드파티 API에 접근할 수 있습니다. + + 업데이트된 액세스 토큰이 반환됩니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 965e936ce3e..7b2f5670192 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -4,7 +4,7 @@ sidebar_position: 4 # 개인 액세스 토큰 (Personal access token) -개인 액세스 토큰 (PAT, Personal access token)은 사용자가 자격 증명과 상호작용 로그인 없이 [액세스 토큰 (Access token)](https://auth.wiki/access-token)을 안전하게 부여할 수 있는 방법을 제공합니다. 이는 CI/CD, 스크립트, 또는 리소스에 프로그래밍 방식으로 접근해야 하는 애플리케이션에 유용합니다. +개인 액세스 토큰 (PAT, Personal access tokens)은 사용자가 자신의 자격 증명과 상호작용 로그인 없이 [액세스 토큰 (Access token)](https://auth.wiki/access-token)을 안전하게 부여할 수 있는 방법을 제공합니다. 이는 CI/CD, 스크립트, 또는 리소스에 프로그래밍 방식으로 접근해야 하는 애플리케이션에 유용합니다. ## 개인 액세스 토큰 관리하기 \{#managing-personal-access-tokens} @@ -22,9 +22,21 @@ sidebar_position: 4 PAT를 생성한 후, 토큰 교환 엔드포인트를 사용하여 애플리케이션에 액세스 토큰을 부여할 수 있습니다. +:::tip 토큰 플로우 동등성 + +PAT를 사용해 얻은 액세스 토큰은 표준 `refresh_token` 플로우로 얻은 토큰과 **동일하게** 동작합니다. 즉: + +- **조직 컨텍스트**: PAT로 얻은 토큰은 refresh token 플로우와 동일한 조직 권한 및 스코프를 지원합니다. +- **인가 플로우**: PAT로 교환한 액세스 토큰을 [조직 권한](/authorization/organization-permissions) 및 [조직 수준 API 리소스](/authorization/organization-level-api-resources)에 사용할 수 있습니다. +- **토큰 검증**: 동일한 검증 로직이 적용되며, 초기 grant type만 다릅니다. + +조직과 함께 작업할 때, PAT 또는 refresh token을 사용하더라도 접근 패턴과 권한은 동일합니다. + +::: + ### 요청(Request) \{#request} -애플리케이션은 HTTP POST 메서드를 사용하여 테넌트의 [토큰 엔드포인트](/integrate-logto/application-data-structure#token-endpoint)에 특수한 grant type으로 [토큰 교환 요청](https://auth.wiki/authorization-code-flow#token-exchange-request)을 보냅니다. 다음 파라미터들은 `application/x-www-form-urlencoded` 형식으로 HTTP 요청 엔티티 본문에 포함됩니다. +애플리케이션은 HTTP POST 메서드를 사용하여 테넌트의 [토큰 엔드포인트](/integrate-logto/application-data-structure#token-endpoint)에 특수 grant type으로 [토큰 교환 요청](https://auth.wiki/authorization-code-flow#token-exchange-request)을 보냅니다. 다음 파라미터들은 `application/x-www-form-urlencoded` 형식으로 HTTP 요청 엔티티 본문에 포함됩니다. 1. `client_id`: 필수. 애플리케이션의 클라이언트 ID. 2. `grant_type`: 필수. 이 파라미터의 값은 `urn:ietf:params:oauth:grant-type:token-exchange`이어야 하며, 토큰 교환이 수행됨을 나타냅니다. @@ -35,9 +47,9 @@ PAT를 생성한 후, 토큰 교환 엔드포인트를 사용하여 애플리케 ### 응답(Response) \{#response} -토큰 교환 요청이 성공하면, 테넌트의 토큰 엔드포인트는 사용자의 아이덴티티를 나타내는 액세스 토큰을 반환합니다. 응답은 `application/json` 형식으로 HTTP 응답 엔티티 본문에 다음 파라미터를 포함합니다. +토큰 교환 요청이 성공하면, 테넌트의 토큰 엔드포인트는 사용자의 아이덴티티를 나타내는 액세스 토큰을 반환합니다. 응답은 `application/json` 형식의 HTTP 응답 엔티티 본문에 다음 파라미터를 포함합니다. -1. `access_token`: 필수. 사용자의 액세스 토큰, `authorization_code` 또는 `refresh_token`과 같은 다른 토큰 요청과 동일합니다. +1. `access_token`: 필수. 사용자의 액세스 토큰으로, `authorization_code` 또는 `refresh_token`과 같은 다른 토큰 요청과 동일합니다. 2. `issued_token_type`: 필수. 발급된 토큰의 유형. 이 파라미터의 값은 `urn:ietf:params:oauth:token-type:access_token`이어야 합니다. 3. `token_type`: 필수. 토큰의 유형. 이 파라미터의 값은 `Bearer`이어야 합니다. 4. `expires_in`: 필수. 액세스 토큰의 유효 기간(초 단위). @@ -70,7 +82,7 @@ Content-Type: application/json } ``` -액세스 토큰 페이로드 예시: +예시 액세스 토큰 페이로드: ```json { @@ -87,10 +99,10 @@ Content-Type: application/json ## 관련 리소스 \{#related-resources} - 개인 액세스 토큰이란 무엇인가요? 언제 개인 액세스 토큰을 사용해야 하나요? + 개인 액세스 토큰이란? 언제 개인 액세스 토큰을 사용해야 할까요? 개인 액세스 토큰, 기계 간 (Machine-to-Machine) 인증 (Authentication), 그리고 API 키의 정의 및 실제 - 사용 사례 + 시나리오 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index 59ed02099ea..62bcad6cdac 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -10,19 +10,21 @@ Logto는 기존 플랫폼에서 기존 사용자를 수동으로 마이그레이 시작하기 전에, Logto의 [사용자 스키마](/user-management/user-data/#user-profile)를 살펴보겠습니다. 사용자 스키마에는 알아두어야 할 3가지 부분이 있습니다: -1. **기본 데이터**: 사용자 프로필의 기본 정보로, 기존 사용자 프로필의 데이터를 매칭할 수 있습니다. -2. **커스텀 데이터**: 추가 사용자 정보를 저장하며, 기본 데이터와 매칭할 수 없는 파일을 저장하는 데 사용할 수 있습니다. +1. **기본 데이터**: 사용자 프로필의 기본 정보로, 기존 사용자 프로필의 데이터를 여기에 매핑할 수 있습니다. +2. **커스텀 데이터**: 추가 사용자 정보를 저장하며, 기본 데이터에 매칭할 수 없는 파일을 저장하는 데 사용할 수 있습니다. 3. **소셜 아이덴티티**: 소셜 로그인에서 가져온 사용자 정보를 저장합니다. 기존 사용자 프로필의 정보를 **기본 데이터**와 **커스텀 데이터**에 매핑하는 맵을 만들 수 있습니다. 소셜 로그인의 경우, 소셜 아이덴티티를 가져오기 위한 추가 단계가 필요합니다. 자세한 내용은 [사용자에 소셜 아이덴티티 연결 API](https://openapi.logto.io/operation/operation-createuseridentity)를 참고하세요. ## 비밀번호 해싱 \{#password-hashing} -Logto는 사용자의 비밀번호를 해싱하기 위해 [Argon2](https://en.wikipedia.org/wiki/Argon2)를 사용하며, 마이그레이션의 편의를 위해 `MD5`, `SHA1`, `SHA256`, `Bcrypt`와 같은 다른 알고리즘도 지원합니다. 이러한 알고리즘은 안전하지 않은 것으로 간주되며, 해당 비밀번호 해시는 사용자가 처음으로 성공적으로 로그인할 때 Argon2로 마이그레이션됩니다. +Logto는 사용자의 비밀번호를 해싱하기 위해 [Argon2](https://en.wikipedia.org/wiki/Argon2)를 사용하며, 마이그레이션의 편의를 위해 `MD5`, `SHA1`, `SHA256`, `Bcrypt`와 같은 다른 알고리즘도 지원합니다. 이러한 알고리즘은 안전하지 않은 것으로 간주되며, 해당 비밀번호 해시는 사용자가 최초로 성공적으로 로그인할 때 Argon2로 마이그레이션됩니다. -다른 해싱 알고리즘이나 솔트를 사용하는 경우, `passwordAlgorithm`을 `Legacy`로 설정할 수 있습니다. 이렇게 하면 Node.js에서 지원하는 모든 해시 알고리즘을 사용할 수 있습니다. 지원되는 알고리즘 목록은 [Node.js crypto 문서](https://nodejs.org/api/crypto.html#cryptogethashes)에서 확인할 수 있습니다. 이 경우, `passwordDigest`는 해시 알고리즘과 기타 알고리즘별 매개변수를 포함하는 JSON 문자열이 됩니다. +다른 해싱 알고리즘이나 솔트를 사용하는 경우, `passwordAlgorithm`을 `Legacy`로 설정할 수 있습니다. 이를 통해 Node.js에서 지원하는 모든 해시 알고리즘을 사용할 수 있습니다. 지원되는 알고리즘 목록은 [Node.js crypto 문서](https://nodejs.org/api/crypto.html#cryptogethashes)에서 확인할 수 있습니다. 이 경우, `passwordDigest`는 해시 알고리즘과 기타 알고리즘별 매개변수를 포함하는 JSON 문자열이 됩니다. -JSON 문자열의 형식은 다음과 같습니다: +### 일반 Legacy 포맷 \{#general-legacy-format} + +JSON 문자열의 포맷은 다음과 같습니다: ```json ["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"] @@ -30,7 +32,7 @@ JSON 문자열의 형식은 다음과 같습니다: 그리고 인자에서 실제 비밀번호 값의 자리에는 `@`를 플레이스홀더로 사용할 수 있습니다. -예를 들어, SHA256과 솔트를 사용하는 경우, 비밀번호를 다음과 같은 형식으로 저장할 수 있습니다: +예를 들어, SHA256과 솔트를 사용하는 경우 다음과 같이 비밀번호를 저장할 수 있습니다: ```json ["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"] @@ -44,10 +46,40 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### PBKDF2 지원 \{#pbkdf2-support} + +Logto는 [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2)를 특별히 지원합니다. + +PBKDF2로 해싱된 비밀번호를 마이그레이션하려면, `passwordAlgorithm`을 `Legacy`로 설정하고 `passwordDigest`를 다음과 같이 포맷하세요: + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +매개변수는 다음과 같습니다: + +- **`salt`**: 원래 해싱에 사용된 솔트 값 +- **`iterations`**: 반복 횟수 (예: `"1000"`) +- **`keylen`**: 파생 키의 바이트 길이 (예: `"20"`) +- **`digest`**: 사용된 해시 함수 (예: `"sha512"`, `"sha256"`, `"sha1"`) +- **`@`**: 실제 비밀번호 값의 플레이스홀더 +- **`expected_hashed_value`**: 16진수 문자열로 된 예상 해시 결과 + +**마이그레이션 예시 페이로드:** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## 마이그레이션 단계 \{#steps-to-migrate} 1. **사용자 데이터 준비** - 먼저 기존 플랫폼에서 사용자 데이터를 내보낸 후, 사용자 정보를 Logto 사용자 스키마에 매핑해야 합니다. 매핑된 데이터를 JSON 형식으로 준비하는 것을 권장합니다. 다음은 사용자 데이터 예시입니다: + 먼저 기존 플랫폼에서 사용자 데이터를 내보낸 후, 사용자 정보를 Logto 사용자 스키마에 매핑해야 합니다. 매핑된 데이터를 JSON 형식으로 준비하는 것을 권장합니다. 사용자 데이터 예시는 다음과 같습니다: ```json [ @@ -67,9 +99,9 @@ const expectedHashedValue = hash.digest('hex'); 2. **Logto 테넌트 생성** Logto에서 테넌트를 설정해야 합니다. Logto Cloud 또는 Logto OSS를 사용할 수 있습니다. 아직 설정하지 않았다면, [Logto Cloud 설정](/introduction/set-up-logto-cloud/#create-logto-tenant) 가이드를 참고하세요. 3. **Management API 연결 설정** - Management API를 사용하여 사용자 데이터를 가져올 예정입니다. 개발 환경에서 연결을 설정하는 방법은 [Management API](/integrate-logto/interact-with-management-api)를 참고하세요. + 사용자 데이터를 가져오기 위해 Management API를 사용할 것입니다. 개발 환경에서 연결을 설정하는 방법은 [Management API](/integrate-logto/interact-with-management-api)를 참고하세요. 4. **사용자 데이터 가져오기** - 사용자 데이터를 하나씩 가져오는 스크립트를 준비하는 것이 좋습니다. [사용자 생성](https://openapi.logto.io/operation/operation-createuser) API를 호출하여 사용자 데이터를 가져올 수 있습니다. 다음은 스크립트 예시입니다: + 사용자 데이터를 하나씩 가져오는 스크립트를 준비하는 것이 좋습니다. [create user](https://openapi.logto.io/operation/operation-createuser) API를 호출하여 사용자 데이터를 가져올 것입니다. 스크립트 예시는 다음과 같습니다: ```jsx const users = require('./users.json'); @@ -98,7 +130,7 @@ const expectedHashedValue = hash.digest('hex'); API 엔드포인트에는 속도 제한이 적용되므로, 각 요청 사이에 대기 시간을 추가해야 합니다. 자세한 내용은 [속도 제한](/integrate-logto/interact-with-management-api/#rate-limit) 페이지를 참고하세요. -사용자 데이터가 대량(10만 명 이상)인 경우, [문의해 주세요](https://logto.io/contact) 속도 제한 상향을 요청할 수 있습니다. +사용자 데이터가 대량(10만 명 이상)인 경우, [문의하기](https://logto.io/contact)를 통해 속도 제한 상향을 요청할 수 있습니다. ## 관련 리소스 \{#related-resources} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index 57ab74eed99..3b254c8ee35 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -4,7 +4,7 @@ ### Uso {#usage} -Logto lida com variáveis de ambiente na seguinte ordem: +O Logto lida com variáveis de ambiente na seguinte ordem: - Variáveis de ambiente do sistema - O arquivo `.env` na raiz do projeto, que está em conformidade com o formato [dotenv](https://github.com/motdotla/dotenv#readme) @@ -19,46 +19,47 @@ Se você executar o Logto via `npm start` na raiz do projeto, `NODE_ENV` será s Nos valores padrão, `protocol` será `http` ou `https` de acordo com sua configuração de HTTPS. -| Key | Valor Padrão | Tipo | Descrição | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Em que tipo de ambiente o Logto está sendo executado. | -| PORT | `3001` | `number` | A porta local que o Logto escuta. | -| ADMIN_PORT | `3002` | `number` | A porta local que o Logto Admin Console escuta. | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Defina como `1` ou `true` para desabilitar a porta para o Admin Console. Com `ADMIN_ENDPOINT` não definido, ele desativará completamente o Admin Console. | -| DB_URL | N/A | `string` | O [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para o banco de dados Logto. | -| HTTPS_CERT_PATH | `undefined` | string | undefined | Veja [Habilitando HTTPS](#enabling-https) para detalhes. | -| HTTPS_KEY_PATH | `undefined` | string | undefined | Idem. | -| TRUST_PROXY_HEADER | `false` | `boolean` | Idem. | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Você pode especificar uma URL com seu domínio personalizado para testes online ou produção. Isso também afetará o valor do [identificador do emissor OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Você pode especificar uma URL com seu domínio personalizado para produção (Ex.: `ADMIN_ENDPOINT=https://admin.domain.com`). Isso também afetará o valor dos URIs de redirecionamento do Admin Console. | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Especifica se o nome de usuário é sensível a maiúsculas e minúsculas. Tenha cuidado ao modificar este valor; mudanças não ajustarão automaticamente os dados existentes no banco de dados, exigindo gerenciamento manual. | +| Key | Valor Padrão | Tipo | Descrição | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Qual tipo de ambiente em que o Logto está rodando. | +| PORT | `3001` | `number` | A porta local na qual o Logto escuta. | +| ADMIN_PORT | `3002` | `number` | A porta local na qual o Logto Admin Console escuta. | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | Defina como `1` ou `true` para desabilitar a porta do Admin Console. Com `ADMIN_ENDPOINT` não definido, irá desabilitar completamente o Admin Console. | +| DB_URL | N/A | `string` | O [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para o banco de dados do Logto. | +| HTTPS_CERT_PATH | `undefined` | string | undefined | Veja [Habilitando HTTPS](#enabling-https) para detalhes. | +| HTTPS_KEY_PATH | `undefined` | string | undefined | Idem. | +| TRUST_PROXY_HEADER | `false` | `boolean` | Idem. | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | Você pode especificar uma URL com seu domínio personalizado para testes online ou produção. Isso também afetará o valor do [identificador do emissor OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | Você pode especificar uma URL com seu domínio personalizado para produção (Ex: `ADMIN_ENDPOINT=https://admin.domain.com`). Isso também afetará o valor dos URIs de redirecionamento do Admin Console. | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Especifica se o nome de usuário diferencia maiúsculas de minúsculas. Tenha cautela ao modificar este valor; alterações não ajustarão automaticamente os dados existentes no banco de dados, exigindo gerenciamento manual. | +| SECRET_VAULT_KEK | `undefined` | `string` | A Key Encryption Key (KEK) usada para criptografar as Data Encryption Keys (DEK) no [Secret Vault](/secret-vault). Necessária para o funcionamento adequado do Secret Vault. Deve ser uma string codificada em base64. AES-256 (32 bytes) é recomendado. Exemplo: `crypto.randomBytes(32).toString('base64')` | ### Habilitando HTTPS {#enabling-https} #### Usando Node {#using-node} -Node suporta HTTPS nativamente. Forneça **AMBOS** `HTTPS_CERT_PATH` e `HTTPS_KEY_PATH` para habilitar HTTPS via Node. +O Node suporta HTTPS nativamente. Forneça **AMBOS** `HTTPS_CERT_PATH` e `HTTPS_KEY_PATH` para habilitar HTTPS via Node. -`HTTPS_CERT_PATH` implica o caminho para o seu certificado HTTPS, enquanto `HTTPS_KEY_PATH` implica o caminho para a sua chave HTTPS. +`HTTPS_CERT_PATH` indica o caminho para seu certificado HTTPS, enquanto `HTTPS_KEY_PATH` indica o caminho para sua chave HTTPS. #### Usando um proxy HTTPS {#using-a-https-proxy} -Outra prática comum é ter um proxy HTTPS na frente do Node (Ex.: Nginx). +Outra prática comum é ter um proxy HTTPS na frente do Node (Ex: Nginx). -Nesse caso, você provavelmente desejará definir `TRUST_PROXY_HEADER` como `true`, o que indica se os campos de cabeçalho do proxy devem ser confiáveis. Logto passará o valor para as [configurações do aplicativo Koa](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). +Nesse caso, provavelmente você vai querer definir `TRUST_PROXY_HEADER` como `true`, o que indica se os campos de cabeçalho do proxy devem ser confiáveis. O Logto irá passar o valor para as [configurações do app Koa](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). -Veja [Confiando em proxies de descarregamento TLS](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) para saber quando configurar este campo. +Veja [Confiando em proxies de offloading TLS](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) para saber quando configurar este campo. ## Configurações do banco de dados {#database-configs} -Gerenciar muitas variáveis de ambiente não é eficiente e flexível, então a maioria de nossas configurações gerais são armazenadas na tabela do banco de dados `logto_configs`. +Gerenciar muitas variáveis de ambiente não é eficiente nem flexível, então a maioria das nossas configurações gerais são armazenadas na tabela `logto_configs` do banco de dados. -A tabela é um armazenamento simples de chave-valor, e a chave é enumerável como segue: +A tabela é um armazenamento simples de chave-valor, e a chave é enumerável conforme a seguir: -| Key | Tipo | Descrição | -| ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| oidc.cookieKeys | string[] | O array de strings das [chaves de assinatura de cookies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | -| oidc.privateKeys | string[] | O array de strings do conteúdo da chave privada para [assinatura de JWT OIDC](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | +| Key | Tipo | Descrição | +| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| oidc.cookieKeys | string[] | O array de strings das [chaves de assinatura de cookies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys). | +| oidc.privateKeys | string[] | O array de strings do conteúdo da chave privada para [assinatura JWT OIDC](https://openid.net/specs/openid-connect-core-1_0.html#Signing). | ### Tipos de chave privada suportados {#supported-private-key-types} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index caa79c3de32..66369f362f6 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -11,9 +11,9 @@ import Oidc from '@site/docs/connectors/assets/icons/sso-oidc.svg'; import Okta from '@site/docs/connectors/assets/icons/sso-okta.svg'; import Saml from '@site/docs/connectors/assets/icons/sso-saml.svg'; -A [solução de autenticação única (SSO)](/end-user-flows/enterprise-sso) do Logto simplifica o gerenciamento de acesso para seus clientes corporativos. Os conectores de SSO corporativo são essenciais para habilitar o SSO para seus diferentes clientes empresariais. +A [solução de autenticação única (SSO)](/end-user-flows/enterprise-sso) do Logto simplifica o gerenciamento de acesso para seus clientes corporativos. Os conectores de SSO corporativo são essenciais para habilitar SSO para seus diferentes clientes empresariais. -Esses conectores facilitam o processo de autenticação entre seu serviço e os IdPs corporativos. O Logto suporta tanto [SSO iniciado pelo SP](/end-user-flows/enterprise-sso/sp-initiated-sso) quanto [SSO iniciado pelo IdP](/end-user-flows/enterprise-sso/idp-initiated-sso), permitindo que membros da organização acessem seus serviços usando suas credenciais corporativas existentes, aumentando a segurança e a produtividade. +Esses conectores facilitam o processo de autenticação entre seu serviço e os IdPs corporativos. O Logto suporta tanto [SSO iniciado pelo SP](/end-user-flows/enterprise-sso/sp-initiated-sso) quanto [SSO iniciado pelo IdP](/end-user-flows/enterprise-sso/idp-initiated-sso), permitindo que membros de organizações acessem seus serviços usando suas credenciais corporativas existentes, aumentando a segurança e a produtividade. ## Conectores corporativos \{#enterprise-connectors} @@ -81,30 +81,31 @@ O Logto fornece conectores pré-construídos para provedores de identidade corpo ]} /> -Se nossos conectores padrão não atenderem às suas necessidades específicas, não hesite em nos contatar. +Se nossos conectores padrão não atenderem aos seus requisitos específicos, não hesite em nos contatar. ## Configurando conectores corporativos \{#configuring-enterprise-connectors} 1. Navegue até: Console > SSO corporativo. 2. Clique no botão "Adicionar conector corporativo" e escolha um tipo de conector. -3. Forneça um nome exclusivo (ex.: Okta para Empresa Acme). +3. Forneça um nome exclusivo (por exemplo, Okta para Empresa Acme). 4. Configure a conexão com seu IdP na guia "Conexão". Consulte os guias acima para cada tipo de conector. 5. Personalize a experiência de SSO e o **domínio de email** na guia "Experiência". -6. Para o conector SAML corporativo, habilitar o SSO iniciado pelo IdP na guia "SSO iniciado pelo IdP" é opcional. [Consulte o guia](/end-user-flows/enterprise-sso/idp-initiated-sso) para detalhes. +6. Para o conector corporativo SAML, habilitar o SSO iniciado pelo IdP na guia "SSO iniciado pelo IdP" é opcional. [Consulte o guia](/end-user-flows/enterprise-sso/idp-initiated-sso) para detalhes. 7. Salve as alterações. Observe as seguintes configurações: -- **Domínios de email**: Se o domínio do email inserido pelo usuário estiver no campo "Domínios de email corporativo" de algum conector SSO corporativo, o usuário será redirecionado para a URL de login correspondente daquele conector SSO. +- **Domínios de email**: Se o domínio do email inserido pelo usuário estiver no campo "Domínios de email corporativo" de algum conector de SSO corporativo, o usuário será redirecionado para a URL de login correspondente daquele conector SSO. :::note É importante observar que, após configurar os domínios de email relevantes em um conector SSO, usuários que fizerem login com emails pertencentes a esses domínios serão obrigados a usar o [login SSO](/end-user-flows/enterprise-sso). - Em outras palavras, apenas emails de domínios que NÃO estão configurados nos conectores SSO podem usar o login "email + código de verificação" ou "email + senha" (desde que esses dois métodos estejam habilitados na experiência de login). + Em outras palavras, apenas emails de domínios que NÃO estão configurados nos conectores SSO podem usar o login "email + código de verificação" ou "email + senha" (desde que esses dois métodos de login estejam habilitados na experiência de login). ::: -- **Sincronizar perfis de usuário**: Escolha quando sincronizar as informações do perfil do usuário (ex.: avatar, nome). O comportamento padrão é "Sincronizar apenas no primeiro login". "Sempre sincronizar a cada login" é outra opção para este campo, mas pode levar à sobrescrição de dados personalizados do usuário. -- **Informações de exibição**: Opcionalmente, personalize o nome de exibição e o logotipo do conector. Isso é muito útil quando múltiplos conectores estão associados ao mesmo domínio de email. Os usuários selecionarão o IdP desejado em uma lista de botões de conectores SSO antes de serem redirecionados para a página de login do IdP. +- **Sincronizar perfis de usuário**: Escolha quando sincronizar as informações do perfil do usuário (por exemplo, avatar, nome). O comportamento padrão é "Sincronizar apenas no primeiro login". "Sempre sincronizar a cada login" é outra opção para este campo, mas pode levar à sobrescrita de dados personalizados do usuário. +- **Habilitar armazenamento de token**: Para conectores corporativos OIDC, você pode habilitar o armazenamento de token para salvar com segurança tokens de acesso e atualização no [Cofre de Segredos](/secret-vault) do Logto quando os usuários fizerem login com um IdP corporativo. Isso permite que seu aplicativo acesse APIs de terceiros em nome do usuário sem exigir nova autenticação. Saiba mais sobre [armazenamento federado de tokens](/secret-vault/federated-token-set). +- **Informações de exibição**: Opcionalmente, personalize o nome de exibição e o logotipo do conector. Isso é muito útil quando vários conectores estão associados ao mesmo domínio de email. Os usuários selecionarão o IdP desejado em uma lista de botões de conectores SSO antes de serem redirecionados para a página de login do IdP. ## Habilitando SSO corporativo \{#enabling-enterprise-sso} @@ -112,7 +113,7 @@ Observe as seguintes configurações: 2. Habilite a opção "SSO corporativo". 3. Salve as alterações. -Uma vez habilitado, um botão "Autenticação única (Single Sign-On)" aparecerá em sua página de login. Usuários corporativos com domínios de email habilitados para SSO poderão acessar seus serviços usando seus provedores de identidade corporativos (IdPs). Para saber mais sobre a experiência do usuário SSO, consulte Fluxos de usuário: [SSO corporativo](/end-user-flows/enterprise-sso). +Uma vez habilitado, um botão "Single Sign-On" aparecerá em sua página de login. Usuários corporativos com domínios de email habilitados para SSO podem acessar seus serviços usando seus provedores de identidade corporativos (IdPs). Para saber mais sobre a experiência do usuário SSO, consulte Fluxos de usuário: [SSO corporativo](/end-user-flows/enterprise-sso). ## Just-in-time para organização \{#just-in-time-to-organization} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/social.mdx index 78438c51a43..307b14b77a0 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,15 +7,15 @@ sidebar_position: 3 # Conectores sociais -Simplifique o onboarding de usuários e aumente as taxas de conversão habilitando o [login social](/end-user-flows/sign-up-and-sign-in/social-sign-in) com Logto. Os usuários podem fazer login de forma rápida e segura usando suas contas de mídia social existentes, eliminando a necessidade de criação de senha ou fluxo de registro complexo. Logto oferece uma variedade de conectores sociais pré-construídos e suporta integrações personalizadas para máxima flexibilidade. +Simplifique o onboarding de usuários e aumente as taxas de conversão ativando o [login social](/end-user-flows/sign-up-and-sign-in/social-sign-in) com Logto. Os usuários podem entrar de forma rápida e segura usando suas contas de redes sociais existentes, eliminando a necessidade de criar senhas ou passar por fluxos de registro complexos. O Logto oferece uma variedade de conectores sociais pré-construídos e suporta integrações personalizadas para máxima flexibilidade. ## Escolha seus conectores sociais \{#choose-your-social-connectors} -Logto oferece dois tipos de conectores sociais: +O Logto oferece dois tipos de conectores sociais: ### Conectores sociais populares \{#popular-social-connectors} -Logto fornece conectores pré-configurados para plataformas sociais populares, prontos para uso imediato. +O Logto fornece conectores pré-configurados para plataformas sociais populares, prontos para uso imediato. ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'O conector do Google fornece uma maneira sucinta para seu aplicativo usar o sistema de autenticação OAuth 2.0 do Google.', + description: 'O conector Google fornece uma maneira sucinta para seu aplicativo usar o sistema de autenticação OAuth 2.0 do Google.', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'O conector do Facebook permite que seu aplicativo use o sistema de autenticação OAuth 2.0 do Facebook.', + description: 'O conector Facebook permite que seu aplicativo use o sistema de autenticação OAuth 2.0 do Facebook.', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'O conector do Microsoft Azure AD fornece uma maneira sucinta para seu aplicativo usar o sistema de autenticação OAuth 2.0 do Azure.', + description: 'O conector Microsoft Azure AD fornece uma maneira sucinta para seu aplicativo usar o sistema de autenticação OAuth 2.0 do Azure.', customProps: { icon: , } @@ -79,7 +79,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Discord', href: '/integrations/discord', - description: 'O conector do Discord fornece uma maneira para seu aplicativo usar o Discord como um sistema de autorização.', + description: 'O conector Discord fornece uma maneira para seu aplicativo usar o Discord como sistema de autorização.', customProps: { icon: , } @@ -119,29 +119,30 @@ Para requisitos personalizados, utilize os padrões OAuth 2.0 e OIDC (OpenID Con /> ``` -Se nossos conectores padrão não atenderem aos seus requisitos específicos, não hesite em [nos contatar](https://logto.productlane.com/roadmap). Para usuários do OSS, você pode [implementar seu conector (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) se o requisito for urgente. Sempre recebemos bem [contribuições](/logto-oss/contribution); seu esforço pode muito bem ajudar outros membros da comunidade com as mesmas necessidades. +Se nossos conectores padrão não atenderem aos seus requisitos específicos, não hesite em [nos contatar](https://logto.productlane.com/roadmap). Para usuários OSS, você pode [implementar seu conector (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector) se a necessidade for urgente. Sempre damos boas-vindas a [contribuições](/logto-oss/contribution); seu esforço pode ajudar outros membros da comunidade com as mesmas necessidades. ## Etapas de configuração \{#configuration-steps} 1. Navegue até Console > Conectores > Conectores sociais. 2. Clique em "Adicionar conector social" e selecione o tipo desejado. -3. Siga o guia README e complete os campos obrigatórios e personalize as configurações. +3. Siga o guia README, preencha os campos obrigatórios e personalize as configurações. 4. Clique em "Salvar e Concluir" para finalizar. 5. Teste o conector iniciando um login social. Observe as seguintes configurações: -- **Nome do provedor de identidade**: Cada conector social tem um nome de Provedor de Identidade (IdP) único para diferenciar identidades de usuários. Enquanto conectores comuns usam um nome de IdP fixo, conectores personalizados exigem um valor único. Saiba mais sobre [nomes de IdP](/connectors/connector-data-structure#target-identity-provider-name) para mais detalhes. -- **Sincronizar perfis de usuários**: Escolha quando sincronizar [informações do perfil do usuário](/user-management/user-data#social-identities) (por exemplo, avatar, nome de usuário). O padrão é "sincronizar apenas no registro". "sincronizar a cada login" é uma alternativa, mas pode sobrescrever dados personalizados do usuário. +- **Nome do provedor de identidade**: Cada conector social possui um nome único de Provedor de Identidade (IdP) para diferenciar as identidades dos usuários. Enquanto conectores comuns usam um nome de IdP fixo, conectores personalizados exigem um valor único. Saiba mais sobre [nomes de IdP](/connectors/connector-data-structure#target-identity-provider-name) para mais detalhes. +- **Sincronizar perfis de usuário**: Escolha quando sincronizar as [informações do perfil do usuário](/user-management/user-data#social-identities) (por exemplo, avatar, nome de usuário). O padrão é "sincronizar apenas no registro". "sincronizar a cada login" é uma alternativa, mas pode sobrescrever dados personalizados do usuário. +- **Habilitar armazenamento de tokens**: Para conectores sociais suportados, você pode habilitar o armazenamento de tokens para salvar com segurança tokens de acesso e atualização no [Cofre de Segredos](/secret-vault) do Logto quando os usuários fizerem login com um provedor social. Isso permite que seu aplicativo acesse APIs de terceiros em nome do usuário sem exigir nova autenticação. Saiba mais sobre [Armazenamento federado de tokens](/secret-vault/federated-token-set). -## Habilitar login social \{#enable-social-sign-in} +## Ative o login social \{#enable-social-sign-in} -Depois de criar um conector social com sucesso, você pode habilitá-lo como um botão de login social (por exemplo, Continuar com Google) na Experiência de Login. +Depois de criar um conector social com sucesso, você pode ativá-lo como um botão de login social (por exemplo, Continuar com Google) na Experiência de Login. -1. Navegue até Console > Experiência de login > Inscrição e login. -2. (Opcional) Escolha "Não aplicável" para o identificador de inscrição se você precisar apenas de login social. -3. Adicione conectores sociais configurados à seção "Login social". -4. Reorganize os conectores conforme necessário. -5. Clique em "Salvar alterações" e teste a "Pré-visualização ao vivo". +1. Navegue até Console > Experiência de login > Cadastro e login. +2. (Opcional) Escolha "Não aplicável" para o identificador de cadastro se você precisar apenas de login social. +3. Adicione os conectores sociais configurados à seção "Login social". +4. Reordene os conectores conforme necessário. +5. Clique em "Salvar alterações" e teste a "Visualização ao vivo". Consulte [Login social](/end-user-flows/sign-up-and-sign-in/social-sign-in) para saber mais detalhes. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index 325b4545d1c..e0c25a283fc 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/facebook sidebar_label: Facebook sidebar_custom_props: - description: Facebook é uma plataforma de mídia social mundial com bilhões de usuários. + description: O Facebook é uma plataforma de mídia social mundial com bilhões de usuários. tutorial_config_name: Facebook login --- @@ -12,18 +12,65 @@ import Integration from './_integration.mdx'; # Configurar login social com Facebook -O conector oficial do Logto para login social do Facebook. +Integre o sistema de autenticação OAuth 2.0 do Facebook para habilitar o Login com Facebook, vinculação de contas e acesso seguro às APIs do Facebook. -## Introdução \{#get-started} +## Primeiros passos \{#get-started} -O conector do Facebook fornece uma maneira concisa para seu aplicativo usar o sistema de autenticação OAuth 2.0 do Facebook. +O conector do Facebook permite a integração OAuth 2.0 para que seu aplicativo possa: + +- Adicionar autenticação “Login com Facebook” +- Vincular contas de usuários a identidades do Facebook +- Sincronizar informações do perfil do usuário do Facebook +- Acessar APIs do Facebook por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas de automação (por exemplo, responder a tópicos; publicar conteúdo e vídeos em seu aplicativo) + +Para configurar esses recursos de autenticação, crie primeiro um conector do Facebook no Logto: + +1. Acesse [Logto > Conector > Conector social](https://cloud.logto.io/to/connectors/social). +2. Clique em **Adicionar conector social**, selecione **Facebook**, clique em **Próximo** e siga o tutorial passo a passo para concluir a integração. -## Referências \{#references} +## Utilizar o conector do Facebook \{#utilize-the-facebook-connector} + +Depois de criar um conector do Facebook e conectá-lo ao Facebook, você pode incorporá-lo aos fluxos de experiência do usuário final. Escolha as opções que correspondem às suas necessidades: + +### Habilitar "Login com Facebook" \{#enable-sign-in-with-facebook} + +1. No Logto Console, vá para Experiência de login > Cadastro e login +2. Adicione o conector do Facebook na seção **Login social** para permitir que os usuários se autentiquem com o Facebook + +Saiba mais sobre a [experiência de login social](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular ou desvincular uma conta do Facebook \{#link-or-unlink-a-facebook-account} + +Use a Account API para construir um Centro de Conta personalizado em seu aplicativo que permita aos usuários autenticados vincular ou desvincular sua conta do Facebook. [Siga o tutorial da Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +É permitido habilitar o conector do Facebook apenas para vinculação de contas e acesso à API, sem habilitá-lo para login social. +::: + +### Acessar a API do Facebook e realizar ações \{#access-facebook-api-and-perform-actions} + +Seu aplicativo pode recuperar tokens de acesso do Facebook armazenados no Secret Vault para chamar APIs do Facebook e automatizar tarefas de backend (por exemplo, publicar conteúdo ou gerenciar postagens). Consulte o guia sobre como recuperar tokens armazenados para acesso à API. + +## Gerenciar a identidade do usuário no Facebook \{#manage-user-s-facebook-identity} + +Após um usuário vincular sua conta do Facebook, os administradores podem gerenciar essa conexão no Logto Console: + +1. Navegue até Gerenciamento de usuários e abra o perfil do usuário. +2. Em **Conexões sociais**, localize o item do Facebook e clique em **Gerenciar**. +3. Nesta página, os administradores podem gerenciar a conexão do usuário com o Facebook, ver todas as informações de perfil concedidas e sincronizadas da conta do Facebook e verificar o status do token de acesso. + +:::note +A resposta do token de acesso do Facebook não inclui informações específicas de escopo, portanto, o Logto não pode exibir diretamente a lista de permissões concedidas pelo usuário. No entanto, desde que o usuário tenha consentido com os escopos solicitados durante a autorização, seu aplicativo terá as permissões correspondentes ao acessar a API do Facebook. Recomenda-se configurar com precisão os escopos necessários tanto no Facebook Developer Console quanto no Logto para garantir que seu aplicativo tenha o acesso necessário. +::: + +## Referência \{#reference} + +Facebook for Developers - Documentação -- [Facebook Login - Documentation - Facebook for Developers](https://developers.facebook.com/docs/facebook-login/) - - [Construir manualmente um fluxo de login](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [Guia de Permissões](https://developers.facebook.com/docs/facebook-login/guides/permissions) + + Documentação do Login com Facebook + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index 50a9ff46e54..d9d4f1373cd 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,55 +1,100 @@ -### Registre uma conta de desenvolvedor do Facebook \{#register-a-facebook-developer-account} +## Etapa 1: Configure um aplicativo no Painel do Facebook App \{#step-1-set-up-an-app-on-facebook-app-dashboard} -[Registre-se como um Desenvolvedor do Facebook](https://developers.facebook.com/docs/development/register/) se você ainda não tiver uma conta +Antes de usar o Facebook como um provedor de autenticação, você deve configurar um aplicativo na plataforma de desenvolvedores do Facebook para obter credenciais OAuth 2.0. -### Configure um aplicativo do Facebook \{#set-up-a-facebook-app} +1. [Registre-se como Desenvolvedor do Facebook](https://developers.facebook.com/docs/development/register/) se ainda não tiver uma conta. +2. Visite a página de [Apps](https://developers.facebook.com/apps). +3. Clique em seu aplicativo existente ou [crie um novo](https://developers.facebook.com/docs/development/create-an-app) se necessário. -1. Visite a página de [Apps](https://developers.facebook.com/apps). -2. Clique no seu aplicativo existente ou [crie um novo](https://developers.facebook.com/docs/development/create-an-app) se necessário. - - O [tipo de aplicativo](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types) selecionado é de sua escolha, mas deve ter o produto _Facebook Login_. -3. Na página do painel do aplicativo, role até a seção "Adicionar um produto" e clique no botão "Configurar" no cartão "Facebook Login". -4. Pule a página de início rápido do Facebook Login e clique na barra lateral -> "Produtos" -> "Facebook Login" -> "Configurações". -5. Na página de Configurações do Facebook Login, preencha `${your_logto_origin}/callback/${connector_id}` no campo "Valid OAuth Redirect URIs". O `connector_id` pode ser encontrado na barra superior da página de detalhes do conector do Logto Admin Console. Exemplo: - - `https://logto.dev/callback/${connector_id}` para produção - - `https://localhost:3001/callback/${connector_id}` para testes no ambiente local -6. Clique no botão "Salvar alterações" no canto inferior direito. +:::tip +Um caso de uso é a principal forma como seu aplicativo irá interagir com a Meta e determina quais APIs, recursos, permissões e produtos estarão disponíveis para seu aplicativo. Se você precisa apenas de autenticação social (para obter email & public_profile), selecione "Authentication and request data from users with Facebook Login". Se quiser acessar APIs do Facebook, escolha seus casos de uso preferidos — a maioria deles também suporta a integração do "Facebook Login for business" após a criação do aplicativo. +::: -## Compor o JSON do conector \{#compose-the-connector-json} +4. Após a criação do aplicativo, na página do painel do aplicativo, navegue até **Use cases > Facebook Login > Settings** ou **Facebook Login for business > Settings**. +5. Preencha o campo **Valid OAuth Redirect URIs** com o **Callback URI** do Logto (copie isso do seu conector Facebook do Logto). Após os usuários fazerem login com o Facebook, eles serão redirecionados para cá com um código de autorização que o Logto usa para finalizar a autenticação. +6. Navegue até **Use cases** e clique em **Customize** do seu caso de uso para adicionar os escopos. Recomendamos adicionar `email` e `public_profile`, que são necessários para implementar o login com Facebook no Logto. -1. Na página do painel do aplicativo do Facebook, clique na barra lateral -> "Configurações" -> "Básico". -2. Você verá o "App ID" e o "App secret" no painel. -3. Clique no botão "Mostrar" ao lado da caixa de entrada do App secret para copiar seu conteúdo. -4. Preencha as configurações do conector do Logto: - - Preencha o campo `clientId` com a string do _App ID_. - - Preencha o campo `clientSecret` com a string do _App secret_. - - Preencha o campo `scope` com uma lista separada por vírgula ou espaço de [permissões](https://developers.facebook.com/docs/permissions/reference) em string. Se você não especificar um escopo, o escopo padrão é `email,public_profile`. +## Etapa 2: Configure o conector Logto com as credenciais do cliente \{#step-2-set-up-logto-connector-with-client-credentials} -## Testar login com usuários de teste do Facebook \{#test-sign-in-with-facebooks-test-users} +1. No Painel do Facebook App, clique na barra lateral em **App settings > Basic**. +2. Você verá o **App ID** e o **App secret** no painel. +3. Clique no botão **Show** ao lado do campo App secret para revelar e copiar seu conteúdo. +4. Configure as definições do seu conector Facebook do Logto: + - Preencha o campo `clientId` com o **App ID**. + - Preencha o campo `clientSecret` com o **App secret**. + - Clique em **Save and Done** no Logto para conectar seu sistema de identidade ao Facebook. -Você pode usar as contas dos usuários de teste, desenvolvedores e administradores para testar o login com o aplicativo relacionado em ambos os [modos de aplicativo](https://developers.facebook.com/docs/development/build-and-test/app-modes) de desenvolvimento e ao vivo. +## Etapa 3: Configure os escopos \{#step-3-configure-scopes} -Você também pode [colocar o aplicativo ao vivo](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode) diretamente para que qualquer usuário do Facebook possa fazer login com o aplicativo. +Os escopos definem as permissões que seu aplicativo solicita aos usuários e controlam quais dados privados seu projeto pode acessar das contas do Facebook deles. -- Na página do painel do aplicativo, clique na barra lateral -> "Funções" -> "Usuários de Teste". -- Clique no botão "Criar usuários de teste" para criar um usuário de teste. -- Clique no botão "Opções" do usuário de teste existente, e você verá mais operações, por exemplo, "Alterar nome e senha". +### Configure os escopos no Painel do Facebook App \{#configure-scopes-in-facebook-app-dashboard} -## Publicar configurações de login do Facebook \{#publish-facebook-sign-in-settings} +1. Navegue até **Facebook App Dashboard > Use cases** e clique no botão **Customize**. +2. Adicione apenas os escopos que seu aplicativo precisa. Os usuários irão revisar e autorizar essas permissões na tela de consentimento do Facebook: + - **Para autenticação (Obrigatório)**: `email` e `public_profile`. + - **Para acesso à API (Opcional)**: Quaisquer escopos adicionais que seu aplicativo necessite (por exemplo, `threads_content_publish`, `threads_read_replies` para acessar a API do Threads). Consulte a [Documentação do Desenvolvedor Meta](https://developers.facebook.com/docs/) para serviços disponíveis. -Normalmente, apenas os usuários de teste, administradores e desenvolvedores podem fazer login com o aplicativo relacionado em [modo de desenvolvimento](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode). +### Configure os escopos no Logto \{#configure-scopes-in-logto} -Para permitir que usuários normais do Facebook façam login com o aplicativo no ambiente de produção, talvez seja necessário mudar seu aplicativo do Facebook para o _[modo ao vivo](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_, dependendo do tipo de aplicativo. -Por exemplo, o aplicativo de _tipo empresarial_ puro não tem o botão de alternância "ao vivo", mas isso não impedirá seu uso. +Escolha uma ou mais das abordagens abaixo conforme sua necessidade: -1. Na página do painel do aplicativo do Facebook, clique na barra lateral -> "Configurações" -> "Básico". -2. Preencha os campos "URL da Política de Privacidade" e "Exclusão de dados do usuário" no painel, se necessário. -3. Clique no botão "Salvar alterações" no canto inferior direito. -4. Clique no botão de alternância "Ao vivo" na barra superior do aplicativo. +**Opção 1: Não precisa de escopos extras de API** -## Tipos de configuração \{#config-types} +- Deixe o campo `Scopes` em branco no seu conector Facebook do Logto. +- O escopo padrão `email public_profile` será solicitado para garantir que o Logto possa obter corretamente as informações básicas do usuário. -| Nome | Tipo | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**Opção 2: Solicitar escopos adicionais no login** + +- Insira todos os escopos desejados no campo **Scopes**, separados por espaços. +- Quaisquer escopos listados aqui substituem os padrões, então sempre inclua os escopos de autenticação: `email public_profile`. + +**Opção 3: Solicitar escopos incrementais posteriormente** + +- Após o usuário fazer login, você pode solicitar escopos adicionais sob demanda reiniciando um fluxo de autorização social federado e atualizando o conjunto de tokens armazenados dos usuários. +- Esses escopos adicionais não precisam ser preenchidos no campo `Scopes` do seu conector Facebook do Logto, e podem ser obtidos através da Social Verification API do Logto. + +Seguindo esses passos, seu conector Facebook do Logto solicitará exatamente as permissões que seu aplicativo precisa — nem mais, nem menos. + +:::tip +Se seu aplicativo solicitar esses escopos para acessar a API do Facebook e realizar ações, certifique-se de habilitar **Store tokens for persistent API access** no conector Facebook do Logto. Veja a próxima seção para detalhes. +::: + +## Etapa 4: Configurações gerais \{#step-4-general-settings} + +Aqui estão algumas configurações gerais que não bloqueiam a conexão com o Facebook, mas podem afetar a experiência de autenticação do usuário final. + +### Sincronizar informações do perfil \{#sync-profile-information} + +No conector do Facebook, você pode definir a política para sincronizar informações do perfil, como nomes de usuário e avatares. Escolha entre: + +- **Sincronizar apenas no cadastro**: As informações do perfil são buscadas uma vez quando o usuário faz login pela primeira vez. +- **Sempre sincronizar no login**: As informações do perfil são atualizadas toda vez que o usuário faz login. + +### Armazenar tokens para acessar APIs do Facebook (Opcional) \{#store-tokens-to-access-facebook-apis-optional} + +Se você deseja acessar APIs do Facebook e realizar ações com autorização do usuário (seja via login social ou vinculação de conta), o Logto precisa obter escopos específicos de API e armazenar tokens. + +1. Adicione os escopos necessários seguindo o tutorial acima. +2. Habilite **Store tokens for persistent API access** no conector Facebook do Logto. O Logto armazenará com segurança os tokens de acesso do Facebook no Secret Vault. + +:::note +O Facebook não fornece tokens de atualização. No entanto, quando o armazenamento de tokens está habilitado, o Logto solicita automaticamente um token de acesso de longa duração (60 dias) na autenticação do usuário. Durante esse período, os usuários podem revogar manualmente os tokens de acesso, mas, caso contrário, não precisarão de nova autorização para acessar as APIs do Facebook. Observação: Não adicione `offline_access` ao campo `Scope`, pois isso pode causar erros. +::: + +## Etapa 5: Teste o login com usuários de teste do Facebook (Opcional) \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +Você pode usar contas de usuário de teste, desenvolvedor e administrador para testar o login com o aplicativo. Você também pode publicar o aplicativo diretamente para que qualquer usuário do Facebook possa fazer login. + +1. No Painel do Facebook App, clique na barra lateral em **App roles > Test Users**. +2. Clique no botão **Create test users** para criar um usuário de teste. +3. Clique no botão **Options** de um usuário de teste existente para ver mais operações, como "Change name and password". + +## Etapa 6: Publique as configurações de login do Facebook \{#step-6-publish-facebook-sign-in-settings} + +Normalmente, apenas usuários de teste, administradores e desenvolvedores podem fazer login com o aplicativo. Para permitir que usuários normais do Facebook façam login com o aplicativo em ambiente de produção, pode ser necessário publicar este aplicativo. + +1. No Painel do Facebook App, clique na barra lateral em **Publish**. +2. Preencha os campos **Privacy Policy URL** e **User data deletion** se necessário. +3. Clique no botão **Save changes** no canto inferior direito. +4. Clique no botão **Live** na barra superior do aplicativo. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index 30b06967de0..a23d1b0f7bb 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -11,28 +11,73 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configurar login social com GitHub +# Configurar login social com GitHub (Set up social login with GitHub) -O conector oficial do Logto para login social do GitHub. +Integre o aplicativo GitHub OAuth para habilitar o login com GitHub, vinculação de contas e acesso seguro às APIs do GitHub. -## Introdução \{#get-started} +## Primeiros passos \{#get-started} -O conector do GitHub permite que os usuários finais façam login em seu aplicativo usando suas próprias contas do GitHub via protocolo de autenticação OAuth 2.0 do GitHub. +O conector do GitHub permite integração OAuth 2.0 para que seu aplicativo possa: + +- Adicionar autenticação "Sign-in with GitHub" +- Vincular contas de usuário a identidades do GitHub +- Sincronizar informações do perfil do usuário do GitHub +- Acessar APIs do GitHub por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas de automação (por exemplo, criar issues no GitHub, gerenciar repositórios a partir do seu app) + +Para configurar esses recursos de autenticação, crie primeiro um conector do GitHub no Logto: + +1. Vá para Console Logto > Conector > Conector social. +2. Clique em **Adicionar conector social**, selecione **GitHub**, clique em **Próximo** e siga o tutorial passo a passo para concluir a integração. -## Testar conector do GitHub \{#test-github-connector} +## Utilizar o conector do GitHub \{#utilize-the-github-connector} + +Depois de criar um conector do GitHub e conectá-lo ao GitHub, você pode incorporá-lo aos fluxos de usuários finais. Escolha as opções que atendem às suas necessidades: + +### Habilitar "Sign-in with GitHub" \{#enable-sign-in-with-github} + +1. No Console Logto, acesse Experiência de login > Cadastro e login. +2. Adicione o conector do GitHub na seção **Login social** para permitir que os usuários se autentiquem com o GitHub. + +Saiba mais sobre a [experiência de login social](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular ou desvincular uma conta do GitHub \{#link-or-unlink-a-github-account} + +Use a Account API para criar um Centro de Conta personalizado em seu aplicativo, permitindo que usuários autenticados vinculem ou desvinculem sua conta do GitHub. [Siga o tutorial da Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -É isso. O conector do GitHub deve estar disponível agora. Não se esqueça de [Habilitar conector social na experiência de login](/connectors/social-connectors/#enable-social-sign-in). +:::tip +É permitido habilitar o conector do GitHub apenas para vinculação de contas e acesso à API, sem habilitá-lo para login social. +::: + +### Acessar APIs do GitHub e realizar ações \{#access-github-apis-and-perform-actions} + +Seu aplicativo pode recuperar tokens de acesso do GitHub armazenados no Secret Vault para chamar APIs do GitHub e automatizar tarefas de backend (por exemplo, criar issues, gerenciar repositórios ou automatizar fluxos de trabalho). Consulte o guia sobre como recuperar tokens armazenados para acesso à API. + +## Gerenciar a identidade do usuário no GitHub \{#manage-user-s-github-identity} + +Após um usuário vincular sua conta do GitHub, administradores podem gerenciar essa conexão no Console Logto: + +1. Navegue até Console Logto > Gerenciamento de usuários e abra o perfil do usuário. +2. Em **Conexões sociais**, localize o item do GitHub e clique em **Gerenciar**. +3. Nesta página, os administradores podem gerenciar a conexão do usuário com o GitHub, ver todas as informações de perfil concedidas e sincronizadas da conta do GitHub e verificar o status do token de acesso. + +:::note +A resposta do token de acesso do GitHub não inclui informações específicas de escopo, portanto, o Logto não pode exibir diretamente a lista de permissões concedidas pelo usuário. No entanto, desde que o usuário tenha consentido com os escopos solicitados durante a autorização, seu aplicativo terá as permissões correspondentes ao acessar a API do GitHub. +::: ## Referência \{#reference} - GitHub - Developers - Apps + Documentação do GitHub Developer - Sobre Apps - GitHub - Developers - Apps - Creating an OAuth App + Documentação do GitHub Developer - Criando um OAuth App + + + + Documentação de Escopos do GitHub OAuth App diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index a1bec67f618..2ecee53e55d 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,35 +1,99 @@ -### Fazer login com conta do GitHub \{#sign-in-with-github-account} +## Etapa 1: Crie um aplicativo OAuth no GitHub \{#step-1-create-an-oauth-app-on-github} -Vá para o [site do GitHub](https://github.com/) e faça login com sua conta do GitHub. Você pode registrar uma nova conta se não tiver uma. +Antes de poder usar o GitHub como um provedor de autenticação, você deve criar um aplicativo OAuth no GitHub para obter credenciais OAuth 2.0. -### Criar e configurar aplicativo OAuth \{#create-and-configure-oauth-app} +1. Acesse o [GitHub](https://github.com/) e faça login com sua conta, ou crie uma nova conta se necessário. +2. Navegue até [Settings > Developer settings > OAuth apps](https://github.com/settings/developers). +3. Clique em **New OAuth App** para registrar um novo aplicativo: + - **Application name**: Insira um nome descritivo para seu aplicativo. + - **Homepage URL**: Insira a URL da página inicial do seu aplicativo. + - **Authorization callback URL**: Copie o **Callback URI** do seu conector GitHub do Logto e cole aqui. Após os usuários fazerem login com o GitHub, eles serão redirecionados para cá com um código de autorização que o Logto usa para concluir a autenticação. + - **Application description**: (Opcional) Adicione uma breve descrição do seu aplicativo. +4. Clique em **Register application** para criar o aplicativo OAuth. -Siga o guia de [criação de um aplicativo OAuth](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) e registre um novo aplicativo. +:::note +Sugerimos não marcar a caixa **Enable Device Flow**, pois usuários que fizerem login com o GitHub em dispositivos móveis precisariam confirmar a ação inicial de login no aplicativo móvel do GitHub. Muitos usuários do GitHub não instalam o aplicativo móvel do GitHub em seus telefones, o que pode bloquear o fluxo de login. Só habilite isso se você espera que os usuários finais confirmem o fluxo de login pelo aplicativo móvel do GitHub. Veja detalhes sobre o [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). -Nomeie seu novo aplicativo OAuth em **Nome do aplicativo** e preencha o **URL da página inicial** do aplicativo. Você pode deixar o campo **Descrição do aplicativo** em branco e personalizar o **URL de retorno de chamada de autorização** como `${your_logto_origin}/callback/${connector_id}`. O `connector_id` pode ser encontrado na barra superior da página de detalhes do conector no Logto Admin Console. +Para mais detalhes sobre como configurar aplicativos OAuth do GitHub, veja [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). +::: -:::note +## Etapa 2: Configure seu conector Logto \{#step-2-configure-your-logto-connector} + +Após criar o aplicativo OAuth no GitHub, você será redirecionado para uma página de detalhes onde poderá copiar o Client ID e gerar um Client secret. + +1. Copie o **Client ID** do seu aplicativo OAuth do GitHub e cole no campo `clientId` no Logto. +2. Clique em **Generate a new client secret** no GitHub para criar um novo segredo, depois copie e cole no campo `clientSecret` no Logto. +3. Clique em **Save and Done** no Logto para conectar seu sistema de identidade ao GitHub. + +:::warning +Mantenha seu Client secret seguro e nunca o exponha em código do lado do cliente. Os client secrets do GitHub não podem ser recuperados se perdidos — será necessário gerar um novo. +::: + +## Etapa 3: Configure escopos (Opcional) \{#step-3-configure-scopes-optional} + +Os escopos definem as permissões que seu aplicativo solicita dos usuários e controlam quais dados seu aplicativo pode acessar das contas GitHub deles. + +Use o campo `Scopes` no Logto para solicitar permissões extras do GitHub. Escolha uma das abordagens abaixo conforme sua necessidade: + +### Opção 1: Nenhum escopo extra de API necessário \{#option-1-no-extra-api-scopes-needed} + +- Deixe o campo `Scopes` em branco no seu conector GitHub do Logto. +- O escopo padrão `read:user` será solicitado para garantir que o Logto possa obter corretamente as informações básicas do usuário (por exemplo, email, nome, avatar). -Se você encontrar a mensagem de erro "O redirect_uri DEVE corresponder ao URL de retorno de chamada registrado para este aplicativo." ao fazer login, tente alinhar o URL de retorno de chamada de autorização do seu aplicativo OAuth do GitHub e o URL de redirecionamento do seu aplicativo Logto (incluindo o protocolo) para resolver o problema. +### Opção 2: Solicitar escopos adicionais no login \{#option-2-request-additional-scopes-at-sign-in} +- Veja todos os [escopos disponíveis do GitHub para aplicativos OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) e adicione apenas os escopos que seu aplicativo precisa. +- Insira todos os escopos desejados no campo **Scopes**, separados por espaços. +- Quaisquer escopos listados aqui substituem os padrões, então sempre inclua o escopo de autenticação: `read:user`. +- Escopos adicionais comuns incluem: + - `repo`: Controle total de repositórios privados + - `public_repo`: Acesso a repositórios públicos + - `user:email`: Acesso aos endereços de email do usuário + - `notifications`: Acesso a notificações +- Certifique-se de que todos os escopos estejam escritos corretamente e sejam válidos. Um escopo incorreto ou não suportado resultará em um erro "Invalid scope" do GitHub. + +### Opção 3: Solicitar escopos incrementais posteriormente \{#option-3-request-incremental-scopes-later} + +- Após o usuário fazer login, você pode solicitar escopos adicionais sob demanda reiniciando um fluxo de autorização social federado e atualizando o conjunto de tokens armazenados do usuário. +- Esses escopos adicionais não precisam ser preenchidos no campo `Scopes` do seu conector GitHub do Logto, e podem ser obtidos através da Social Verification API do Logto. + +Seguindo essas etapas, seu conector GitHub do Logto solicitará exatamente as permissões que seu aplicativo precisa — nem mais, nem menos. + +:::tip +Se seu aplicativo solicita esses escopos para acessar a API do GitHub e realizar ações, certifique-se de habilitar **Store tokens for persistent API access** no conector GitHub do Logto. Veja a próxima seção para detalhes. ::: -Sugerimos não marcar a caixa antes de **Habilitar Fluxo de Dispositivo**, ou os usuários que fizerem login com o GitHub em dispositivos móveis deverão confirmar a ação inicial de login no aplicativo GitHub. Muitos usuários do GitHub não instalam o aplicativo móvel do GitHub em seus telefones, o que pode bloquear o fluxo de login. Por favor, ignore nossa sugestão se você espera que os usuários finais confirmem seu fluxo de login. Veja detalhes do [fluxo de dispositivo](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). +## Etapa 4: Configurações gerais \{#step-4-general-settings} + +Aqui estão algumas configurações gerais que não bloqueiam a conexão com o GitHub, mas podem afetar a experiência de autenticação do usuário final. + +### Sincronizar informações de perfil \{#sync-profile-information} -### Gerenciando aplicativos OAuth \{#managing-oauth-apps} +No conector GitHub, você pode definir a política para sincronização das informações de perfil, como nomes de usuário e avatares. Escolha entre: -Vá para a [página de aplicativos OAuth](https://github.com/settings/developers) e você pode adicionar, editar ou excluir aplicativos OAuth existentes. Você também pode encontrar o `Client ID` e gerar `Client secrets` nas páginas de detalhes do aplicativo OAuth. +- **Only sync at sign-up**: As informações de perfil são buscadas apenas uma vez, quando o usuário faz login pela primeira vez. +- **Always sync at sign-in**: As informações de perfil são atualizadas toda vez que o usuário faz login. -### Configurar seu conector \{#configure-your-connector} +### Armazenar tokens para acessar APIs do GitHub (Opcional) \{#store-tokens-to-access-github-apis-optional} + +Se você deseja acessar APIs do GitHub e realizar ações com autorização do usuário (seja via login social ou vinculação de conta), o Logto precisa obter escopos de API específicos e armazenar tokens. + +1. Adicione os escopos necessários seguindo as instruções acima. +2. Habilite **Store tokens for persistent API access** no conector GitHub do Logto. O Logto armazenará com segurança os tokens de acesso do GitHub no Secret Vault. + +:::note +Ao usar um **OAuth App** do GitHub como descrito neste tutorial, você não pode obter um refresh token do GitHub porque o token de acesso não expira, a menos que o usuário o revogue manualmente. Portanto, não é necessário adicionar `offline_access` no campo `Scopes` — fazer isso pode causar um erro. + +Se você deseja que o token de acesso expire ou usar refresh tokens, considere integrar com um **GitHub App** em vez disso. Saiba mais sobre as [diferenças entre GitHub Apps e OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). +::: -Preencha o campo `clientId` e `clientSecret` com o _Client ID_ e _Client Secret_ que você obteve nas páginas de detalhes do aplicativo OAuth mencionadas na seção anterior. +## Etapa 5: Teste sua integração (Opcional) \{#step-5-test-your-integration-optional} -`scope` é uma lista delimitada por espaços de [escopos](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). Se não for fornecido, o escopo padrão será `read:user`. +Antes de ir para produção, teste sua integração com o GitHub: -### Tipos de configuração \{#config-types} +1. Use o conector em um tenant de desenvolvimento do Logto. +2. Verifique se os usuários conseguem fazer login com o GitHub. +3. Confira se os escopos corretos estão sendo solicitados. +4. Teste chamadas de API se você estiver armazenando tokens. -| Nome | Tipo | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +Os aplicativos OAuth do GitHub funcionam com qualquer conta de usuário do GitHub imediatamente — não é necessário criar usuários de teste ou aprovar o aplicativo como em outras plataformas. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index 78bb4de002f..e38d7075423 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: - description: Google é um principal provedor de tecnologia de mecanismo de busca e serviço de email. + description: O Google é uma das principais tecnologias de mecanismo de busca e provedor de serviços de e-mail. tutorial_config_name: Google OAuth app --- @@ -10,16 +10,68 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configurar login social com Google +# Configurar login social com Google (Set up social login with Google) -O conector do Google fornece uma maneira sucinta para seu aplicativo usar o sistema de autenticação OAuth 2.0 do Google. +Integre o sistema de autenticação OAuth 2.0 do Google para habilitar o "Entrar com Google", vinculação de contas e acesso seguro às APIs do Google. +## Comece agora \{#get-started} + +O conector do Google permite a integração OAuth 2.0 para que seu aplicativo possa: + +- Adicionar autenticação "Entrar com Google" +- Vincular contas de usuário a identidades do Google +- Sincronizar informações do perfil do usuário a partir do Google +- Acessar APIs do Google por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas de automação (por exemplo, editar Google Docs, gerenciar eventos do Calendar em seu app) + +Para configurar esses recursos de autenticação, crie primeiro um conector do Google no Logto: + +1. Acesse Logto console > Conector > Conector social. +2. Clique em **Adicionar conector social**, selecione **Google**, clique em **Próximo** e siga o tutorial passo a passo para concluir a integração. + -## Referências \{#references} +## Utilizar o conector do Google \{#utilize-the-google-connector} + +Depois de criar um conector do Google e conectá-lo ao Google, você pode incorporá-lo aos fluxos de experiência do usuário final. Escolha as opções que atendem às suas necessidades: + +### Habilitar "Entrar com Google" \{#enable-sign-in-with-google} + +1. No Logto Console, acesse Experiência de login > Cadastro e login. +2. Adicione o conector do Google na seção **Login social** para permitir que os usuários se autentiquem com o Google. +3. Opcionalmente, habilite o **Google One Tap** nas páginas de login e cadastro para uma experiência de autenticação mais fluida. + +Saiba mais sobre a [experiência de login social](/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular ou desvincular uma conta Google \{#link-or-unlink-a-google-account} + +Use a Account API para construir um Centro de Conta personalizado em seu app que permita aos usuários autenticados vincular ou desvincular sua conta Google. [Siga o tutorial da Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +É permitido habilitar o conector do Google apenas para vinculação de contas e acesso à API, sem habilitá-lo para login social. +::: + +### Acessar APIs do Google e realizar ações \{#access-google-apis-and-perform-actions} + +Seu aplicativo pode recuperar tokens de acesso do Google armazenados no Secret Vault para chamar APIs do Google e automatizar tarefas de backend (por exemplo, gerenciar arquivos do Google Drive, criar eventos no Calendar ou enviar e-mails pelo Gmail). Consulte o guia sobre como recuperar tokens armazenados para acesso à API. + +## Gerenciar a identidade Google do usuário \{#manage-user-s-google-identity} + +Após um usuário vincular sua conta Google, administradores podem gerenciar essa conexão no Logto Console: + +1. Navegue até Logto console > Gerenciamento de usuários e abra o perfil do usuário. +2. Em **Conexões sociais**, localize o item Google e clique em **Gerenciar**. +3. Nesta página, administradores podem gerenciar a conexão Google do usuário, ver todas as informações de perfil concedidas e sincronizadas da conta Google e verificar o status do token de acesso. + +## Referência \{#reference} Google Identity: Configurando OAuth 2.0 + + + Google Identity Services (One Tap) + + +Google Cloud Console diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index f67bc07e326..ed42a5e90f1 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## Configurar um projeto no Google API Console \{#set-up-a-project-in-the-google-api-console} +## Etapa 1: Crie um projeto na Plataforma de Autenticação do Google \{#step-1-create-a-project-on-google-auth-platform} + +Antes de usar o Google como um provedor de autenticação, você deve configurar um projeto no Google Cloud Console para obter credenciais OAuth 2.0. Se você já possui um projeto, pode pular esta etapa. + +1. Acesse o [Google Cloud Console](https://console.cloud.google.com/) e faça login com sua conta Google. +2. Clique no botão **Selecionar um projeto** na barra de menu superior e, em seguida, clique no botão **Novo projeto** para criar um projeto. +3. No seu projeto recém-criado, navegue até **APIs e serviços > Tela de consentimento OAuth** para configurar seu aplicativo: + - **Informações do aplicativo**: Insira o **Nome do aplicativo** e o **E-mail de suporte** que serão exibidos na página de consentimento + - **Público (Audience)**: Selecione o tipo de público preferido: + - **Interno** - Apenas para usuários do Google Workspace dentro da sua organização + - **Externo** - Para qualquer usuário Google (requer verificação para uso em produção) + - **Informações de contato**: Forneça endereços de e-mail para que o Google possa notificá-lo sobre quaisquer alterações em seu projeto + - Marque **Concordo com as políticas do Google** para finalizar a configuração básica +4. Opcionalmente, vá até a seção **Branding** para editar as informações do produto e fazer upload do **Logo do aplicativo**, que aparecerá na tela de consentimento OAuth para ajudar os usuários a reconhecerem seu app. + +:::tip +Se você escolher o tipo de público **Externo**, será necessário adicionar usuários de teste durante o desenvolvimento e publicar seu app para uso em produção. +::: + +## Etapa 2: Crie credenciais OAuth 2.0 \{#step-2-create-oauth-2-0-credentials} + +Navegue até a página de [Credenciais](https://console.cloud.google.com/apis/credentials) no Google Cloud Console e crie credenciais OAuth para seu aplicativo. + +1. Clique em **Criar credenciais > ID do cliente OAuth**. +2. Selecione **Aplicativo da Web** como o tipo de aplicativo. +3. Preencha o **Nome** do seu cliente OAuth. Isso ajuda a identificar as credenciais e não é exibido para os usuários finais. +4. Configure os URIs autorizados: + - **Origens JavaScript autorizadas**: Adicione a origem da sua instância Logto (ex: `https://seu-dominio-logto.com`) + - **URIs de redirecionamento autorizados**: Adicione o **Callback URI** do Logto (copie isso do seu conector Google do Logto) +5. Clique em **Criar** para gerar o cliente OAuth. + +## Etapa 3: Configure o conector Logto com as credenciais \{#step-3-configure-logto-connector-with-credentials} + +Após criar o cliente OAuth, o Google exibirá um modal com suas credenciais: + +1. Copie o **Client ID** e cole no campo `clientId` no Logto +2. Copie o **Client secret** e cole no campo `clientSecret` no Logto +3. Clique em **Salvar e Concluir** no Logto para conectar seu sistema de identidade ao Google + +:::warning +Mantenha seu client secret seguro e nunca o exponha em código do lado do cliente. Se for comprometido, gere um novo imediatamente. +::: + +## Etapa 4: Configure os escopos \{#step-4-configure-scopes} + +Os escopos definem as permissões que seu app solicita dos usuários e controlam quais dados seu app pode acessar das contas Google deles. + +### Configure os escopos no Google Cloud Console \{#configure-scopes-in-google-cloud-console} + +1. Navegue até **APIs e serviços > Tela de consentimento OAuth > Escopos**. +2. Clique em **Adicionar ou remover escopos** e selecione apenas os escopos que seu app necessita: + - **Autenticação (Authentication) (Obrigatório)**: + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **Acesso à API (Opcional)**: Adicione quaisquer escopos adicionais necessários para seu app (ex: Drive, Calendar, YouTube). Navegue pela [Biblioteca de APIs do Google](https://console.cloud.google.com/apis/library) para encontrar serviços disponíveis. Se seu app precisar acessar APIs do Google além das permissões básicas, primeiro ative as APIs específicas que seu app usará (ex: Google Drive API, Gmail API, Calendar API) na Biblioteca de APIs do Google. +3. Clique em **Atualizar** para confirmar a seleção. +4. Clique em **Salvar e continuar** para aplicar as alterações. -- Visite o [Google API Console](https://console.developers.google.com) e faça login com sua conta do Google. -- Clique no botão **Selecionar um projeto** na barra de menu superior e clique no botão **Novo Projeto** para criar um projeto. -- No seu novo projeto, clique em **APIs & Services** para entrar no menu **APIs & Services**. +### Configure os escopos no Logto \{#configure-scopes-in-logto} -## Configurar sua tela de consentimento \{#configure-your-consent-screen} +Escolha uma ou mais das abordagens abaixo conforme sua necessidade: -### Configurar e registrar seu aplicativo \{#configure-and-register-your-application} +**Opção 1: Nenhum escopo extra de API necessário** -- No menu à esquerda **APIs & Services**, clique no botão **Tela de consentimento OAuth**. -- Escolha o **Tipo de Usuário** desejado e clique no botão **Criar**. (Nota: Se você selecionar **Externo** como seu **Tipo de Usuário**, precisará adicionar usuários de teste posteriormente.) +- Deixe o campo `Scopes` em branco no seu conector Google do Logto. +- Os escopos padrão `openid profile email` serão solicitados para garantir que o Logto possa obter corretamente as informações básicas do usuário. -Agora você estará na página **Editar registro de aplicativo**. +**Opção 2: Solicitar escopos adicionais no login** -### Editar registro de aplicativo \{#edit-app-registration} +- Insira todos os escopos desejados no campo **Scopes**, separados por espaços. +- Quaisquer escopos listados aqui substituem os padrões, então sempre inclua os escopos de autenticação: `https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`. +- Use URLs completas dos escopos. Exemplo: `https://www.googleapis.com/auth/calendar.readonly`. -#### Configurar tela de consentimento OAuth \{#config-oauth-consent-screen} +**Opção 3: Solicitar escopos incrementais posteriormente** -- Siga as instruções para preencher o formulário da **Tela de consentimento OAuth**. -- Clique em **SALVAR E CONTINUAR** para continuar. +- Após o usuário fazer login, você pode solicitar escopos adicionais sob demanda reiniciando um fluxo de autorização social federado e atualizando o conjunto de tokens armazenados do usuário. +- Esses escopos adicionais não precisam ser preenchidos no campo `Scopes` do seu conector Google do Logto, e podem ser obtidos através da Social Verification API do Logto. -#### Configurar escopos \{#config-scopes} +Seguindo essas etapas, seu conector Google do Logto solicitará exatamente as permissões que seu app precisa — nem mais, nem menos. -- Clique em **ADICIONAR OU REMOVER ESCOPOS** e selecione `../auth/userinfo.email`, `../auth/userinfo.profile` e `openid` na gaveta pop-up, e clique em **ATUALIZAR** para finalizar. Recomenda-se que você considere adicionar todos os escopos que possa usar, caso contrário, alguns escopos que você adicionou na configuração podem não funcionar. -- Preencha o formulário conforme necessário. -- Clique em **SALVAR E CONTINUAR** para continuar. +:::tip +Se seu app solicitar esses escopos para acessar a API do Google e realizar ações, certifique-se de habilitar **Armazenar tokens para acesso persistente à API** no conector Google do Logto. Veja a próxima seção para detalhes. +::: -#### Adicionar usuários de teste (apenas tipo de usuário externo) \{#add-test-users-external-user-type-only} +## Etapa 5: Personalize os prompts de autenticação \{#step-5-customize-authentication-prompts} -- Clique em **ADICIONAR USUÁRIOS** e adicione usuários de teste para permitir que esses usuários acessem seu aplicativo durante os testes. -- Clique em **SALVAR E CONTINUAR** para continuar. +Configure **Prompts** no Logto para controlar a experiência de autenticação do usuário. Prompts é um array de strings que especifica o tipo de interação do usuário necessária: -Agora você deve ter a tela de consentimento do Google OAuth 2.0 configurada. +- `none` - O servidor de autorização não exibe nenhuma tela de autenticação ou consentimento. Retorna um erro se o usuário ainda não estiver autenticado e não tiver consentimento pré-configurado para os escopos solicitados. Use isso para verificar autenticação e/ou consentimento existentes. +- `consent` - O servidor de autorização solicita consentimento do usuário antes de retornar informações ao cliente. Necessário para habilitar **acesso offline** para acesso à API do Google. +- `select_account` - O servidor de autorização solicita ao usuário que selecione uma conta. Isso permite que usuários com várias contas Google escolham qual conta usar para autenticação. -## Obter credenciais OAuth 2.0 \{#obtain-oauth-20-credentials} +## Etapa 6: Configurações gerais \{#step-6-general-settings} -- No menu à esquerda **APIs & Services**, clique no botão **Credenciais**. -- Na página **Credenciais**, clique no botão **+ CRIAR CREDENCIAIS** na barra de menu superior e selecione **ID do cliente OAuth**. -- Na página **Criar ID do cliente OAuth**, selecione **Aplicativo da Web** como o tipo de aplicativo. -- Preencha as informações básicas do seu aplicativo. -- Clique em **+ Adicionar URI** para adicionar um domínio autorizado à seção **Origens JavaScript autorizadas**. Este é o domínio de onde sua página de autorização do Logto será servida. No nosso caso, será `${your_logto_origin}`. por exemplo, `https://logto.dev`. -- Clique em **+ Adicionar URI** na seção **URIs de redirecionamento autorizados** para configurar os **URIs de redirecionamento autorizados**, que redirecionam o usuário para o aplicativo após o login. No nosso caso, será `${your_logto_endpoint}/callback/${connector_id}`. por exemplo, `https://logto.dev/callback/${connector_id}`. O `connector_id` pode ser encontrado na barra superior da página de detalhes do conector no Logto Admin Console. -- Clique em **Criar** para finalizar e então você obterá o **ID do Cliente** e o **Segredo do Cliente**. +Aqui estão algumas configurações gerais que não bloqueiam a conexão com o Google, mas podem afetar a experiência de autenticação do usuário final. -## Configurar seu conector \{#configure-your-connector} +### Sincronizar informações do perfil \{#sync-profile-information} -Preencha o campo `clientId` e `clientSecret` com o _ID do Cliente_ e o _Segredo do Cliente_ que você obteve das páginas de detalhes do aplicativo OAuth mencionadas na seção anterior. +No conector Google, você pode definir a política para sincronização das informações do perfil, como nomes de usuário e avatares. Escolha entre: -`scope` é uma lista delimitada por espaços de [escopos](https://developers.google.com/identity/protocols/oauth2/scopes). Se não for fornecido, o escopo padrão será `openid profile email`. +- **Sincronizar apenas no cadastro**: As informações do perfil são buscadas uma vez quando o usuário faz login pela primeira vez. +- **Sempre sincronizar no login**: As informações do perfil são atualizadas toda vez que o usuário faz login. -`prompts` é um array de strings que especifica o tipo de interação do usuário que é necessária. A string pode ser um dos seguintes valores: +### Armazenar tokens para acessar APIs do Google (Opcional) \{#store-tokens-to-access-google-apis-optional} -- `none`: O servidor de autorização não exibe nenhuma tela de autenticação ou consentimento do usuário; ele retornará um erro se o usuário não estiver autenticado e não tiver pré-configurado o consentimento para os escopos solicitados. Você pode usar none para verificar a autenticação e / ou consentimento existentes. -- `consent`: O servidor de autorização solicita o consentimento do usuário antes de retornar informações para o cliente. -- `select_account`: O servidor de autorização solicita que o usuário selecione uma conta de usuário. Isso permite que um usuário que possui várias contas no servidor de autorização selecione entre as várias contas para as quais ele pode ter sessões atuais. +Se você deseja acessar [APIs do Google](https://console.cloud.google.com/apis/library) e realizar ações com autorização do usuário (seja via login social ou vinculação de conta), o Logto precisa obter escopos específicos de API e armazenar tokens. -### Tipos de configuração \{#config-types} +1. Adicione os escopos necessários na configuração da tela de consentimento OAuth do Google Cloud Console e no conector Google do Logto. +2. Habilite **Armazenar tokens para acesso persistente à API** no conector Google do Logto. O Logto armazenará com segurança os tokens de acesso e atualização do Google no Cofre de Segredos. +3. Para garantir que tokens de atualização sejam retornados, configure seu conector Google do Logto da seguinte forma: + - Defina **Prompts** para incluir `consent` + - Habilite **Acesso offline** -| Nome | Tipo | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +Você não precisa adicionar `offline_access` no campo `Scope` do Logto — fazer isso pode causar um erro. O Google usa `access_type=offline` automaticamente quando o acesso offline está habilitado. +::: -## Ativar Google One Tap \{#enable-google-one-tap} +## Etapa 7: Habilite o Google One Tap (Opcional) \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) é uma maneira segura e fácil de permitir que os usuários façam login no seu site ou aplicativo com sua conta do Google. +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) é uma forma segura e simplificada de permitir que usuários façam login no seu site com a conta Google usando uma interface pop-up. -Depois de configurar o conector do Google, você verá um cartão para o Google One Tap na página de detalhes do conector. Você pode ativar o Google One Tap nas suas páginas de inscrição e login alternando o interruptor. +Depois de configurar o conector Google, você verá um cartão para o Google One Tap na página de detalhes do conector. Habilite o Google One Tap ativando o interruptor. -Ao ativar o Google One Tap, você pode configurar as seguintes opções: +### Opções de configuração do Google One Tap \{#google-one-tap-configuration-options} -- **Selecionar automaticamente a credencial, se possível**: Fazer login automaticamente no usuário com a conta do Google se [certas condições forem atendidas](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out). -- **Cancelar o prompt se o usuário clicar / tocar fora**: Fechar o prompt do Google One Tap se o usuário clicar ou tocar fora do prompt. Se desativado, o usuário deve clicar no botão de fechar para dispensar o prompt. -- **Ativar UX do One Tap atualizado em navegadores ITP**: Ativar a experiência do usuário do Google One Tap atualizada em navegadores com Prevenção Inteligente de Rastreamento (ITP). Consulte [esta página](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) para mais informações. +- **Selecionar credencial automaticamente se possível** - Faz login automático do usuário com a conta Google se [certas condições forem atendidas](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) +- **Cancelar o prompt se o usuário clicar/tocar fora** - Fecha o prompt do Google One Tap se o usuário clicar ou tocar fora do prompt. Se desabilitado, o usuário deve clicar no botão de fechar para dispensar o prompt. +- **Habilitar UX aprimorado do One Tap em navegadores ITP** - Habilita a experiência aprimorada do Google One Tap em navegadores com Intelligent Tracking Prevention (ITP). Consulte [esta documentação](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) para mais informações. -:::caution -Certifique-se de adicionar a origem do seu servidor à seção **Origens JavaScript autorizadas** na configuração da tela de consentimento OAuth. Caso contrário, o Google One Tap não poderá ser exibido. +:::warning +Certifique-se de adicionar seu domínio na seção **Origens JavaScript autorizadas** na configuração do seu cliente OAuth. Caso contrário, o Google One Tap não poderá ser exibido. ::: +### Limitações importantes com o Google One Tap \{#important-limitations-with-google-one-tap} + +Se você habilitar **Armazenar tokens para acesso persistente à API** junto com o **Google One Tap**, você não receberá automaticamente um token de acesso ou os escopos solicitados. + +O login pelo Google One Tap (diferente do botão padrão "Entrar com o Google") **não** emite um token de acesso OAuth. Ele retorna apenas um token de ID (um JWT assinado) que verifica a identidade do usuário, mas não concede acesso à API. + +Para acessar APIs do Google com usuários do Google One Tap, você pode usar a Social Verification API do Logto para reiniciar um fluxo de autorização social federado após o usuário fazer login com o Google One Tap. Isso permite solicitar escopos adicionais conforme necessário e atualizar o conjunto de tokens armazenados do usuário, sem exigir que os escopos estejam pré-preenchidos no conector Google do Logto. Essa abordagem permite autorização incremental, então os usuários só são solicitados para permissões extras quando seu app realmente precisa delas. + +Saiba mais sobre as [limitações do Google One Tap](https://developers.google.com/identity/gsi/web/guides/overview) na documentação oficial. + +## Etapa 8: Teste e publique seu app \{#step-8-test-and-publish-your-app} + +### Para apps internos \{#for-internal-apps} + +Se o tipo de **Público (Audience)** no Google estiver definido como **Interno**, seu app estará disponível apenas para usuários do Google Workspace dentro da sua organização. Você pode testar usando qualquer conta da sua organização. + +### Para apps externos \{#for-external-apps} + +Se o tipo de **Público (Audience)** for **Externo**: + +1. **Durante o desenvolvimento**: Navegue até **Tela de consentimento OAuth > Usuários de teste** e adicione os endereços de e-mail dos usuários de teste. Apenas esses usuários poderão fazer login com seu app. +2. **Para produção**: Clique em **Publicar app** na seção da tela de consentimento OAuth para disponibilizá-lo para qualquer pessoa com uma Conta Google. + :::note -Para ativar o Google One Tap no seu site (além da experiência de login do Logto), este recurso está em desenvolvimento. Fique atento para atualizações. +Apps com escopos sensíveis ou restritos podem exigir verificação do Google antes de serem publicados. Esse processo pode levar várias semanas. ::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index e214a8e9c6a..2c49f1d1727 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -5,26 +5,36 @@ sidebar_custom_props: description: O framework de autorização OAuth 2.0 permite que um aplicativo de terceiros obtenha acesso limitado a um serviço HTTP. logoFilename: 'oauth.svg' tutorial_name: OAuth2 -tutorial_config_name: Aplicativo padrão OAuth 2.0 +tutorial_config_name: Standard OAuth 2.0 app --- import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configurar login social com protocolo OAuth 2.0 +# Configurar login social com protocolo OAuth 2.0 (Set up social login with OAuth 2.0 protocol) O conector oficial do Logto para o protocolo OAuth 2.0. -## Introdução \{#get-started} +## Primeiros passos \{#get-started} -O conector OAuth permite a conexão do Logto a um provedor de identidade social arbitrário que suporta o protocolo OAuth 2.0. +O conector OAuth permite a conexão do Logto com qualquer provedor de identidade social que suporte o protocolo OAuth 2.0. Use o conector OAuth para permitir que seu aplicativo: + +- Adicione botões de login social +- Vincule contas de usuário a identidades sociais +- Sincronize informações do perfil do usuário a partir do provedor social +- Acesse APIs de terceiros por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas de automação (por exemplo, editar Google Docs, gerenciar eventos do Calendário em seu aplicativo) + +Para configurar esses recursos de autenticação, crie primeiro um conector OAuth 2.0 no Logto: + +1. Vá para Console do Logto > Conector > Conector social. +2. Clique em **Adicionar conector social**, selecione **OAuth 2.0**, clique em **Próximo** e siga o tutorial passo a passo para concluir a integração. :::note -O conector OAuth é um tipo especial de conector no Logto, você pode adicionar alguns conectores baseados no protocolo OAuth. +O conector OAuth é um tipo especial de conector no Logto, você pode adicionar vários conectores baseados no protocolo OAuth. ::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index ab64af2d858..cb280176327 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ ## Crie seu aplicativo OAuth \{#create-your-oauth-app} -Ao abrir esta página, acreditamos que você já sabe qual provedor de identidade social deseja conectar. A primeira coisa a fazer é confirmar se o provedor de identidade suporta o protocolo OAuth, que é um pré-requisito para configurar um conector válido. Em seguida, siga as instruções do provedor de identidade para registrar e criar o aplicativo relevante para autorização OAuth. +Ao abrir esta página, presumimos que você já sabe qual provedor de identidade social deseja conectar. A primeira coisa a fazer é confirmar se o provedor de identidade suporta o protocolo OAuth, que é um pré-requisito para configurar um conector válido. Em seguida, siga as instruções do provedor de identidade para registrar e criar o aplicativo relevante para autorização OAuth. ## Configure seu conector \{#configure-your-connector} -Nós SOMENTE suportamos o tipo de concessão "Authorization Code" por questões de segurança e ele se encaixa perfeitamente no cenário do Logto. +SOMENTE suportamos o tipo de concessão "Authorization Code" por questões de segurança e ele se encaixa perfeitamente no cenário do Logto. -`clientId` e `clientSecret` podem ser encontrados na página de detalhes dos seus aplicativos OAuth. +`clientId` e `clientSecret` podem ser encontrados na página de detalhes do seu aplicativo OAuth. -_clientId_: O client ID é um identificador único que identifica o aplicativo cliente durante o registro com o servidor de autorização. Este ID é usado pelo servidor de autorização para verificar a identidade do aplicativo cliente e associar quaisquer tokens de acesso autorizados a esse aplicativo cliente específico. +_clientId_: O client ID é um identificador único que identifica o aplicativo cliente durante o registro com o servidor de autorização. Esse ID é usado pelo servidor de autorização para verificar a identidade do aplicativo cliente e associar quaisquer tokens de acesso autorizados a esse aplicativo específico. _clientSecret_: O client secret é uma chave confidencial emitida para o aplicativo cliente pelo servidor de autorização durante o registro. O aplicativo cliente usa essa chave secreta para se autenticar com o servidor de autorização ao solicitar tokens de acesso. O client secret é considerado informação confidencial e deve ser mantido seguro o tempo todo. -_tokenEndpointAuthMethod_: O método de autenticação do endpoint de token é usado pelo aplicativo cliente para se autenticar com o servidor de autorização ao solicitar tokens de acesso. Para descobrir métodos suportados, consulte o campo `token_endpoint_auth_methods_supported` disponível no endpoint de descoberta OpenID Connect do provedor de serviços OAuth 2.0, ou consulte a documentação relevante fornecida pelo provedor de serviços OAuth 2.0. +_tokenEndpointAuthMethod_: O método de autenticação do endpoint de token é usado pelo aplicativo cliente para se autenticar com o servidor de autorização ao solicitar tokens de acesso. Para descobrir os métodos suportados, consulte o campo `token_endpoint_auth_methods_supported` disponível no endpoint de descoberta OpenID Connect do provedor de serviço OAuth 2.0, ou consulte a documentação relevante fornecida pelo provedor de serviço OAuth 2.0. -_clientSecretJwtSigningAlgorithm (Opcional)_: Somente necessário quando `tokenEndpointAuthMethod` é `client_secret_jwt`. O algoritmo de assinatura JWT do client secret é usado pelo aplicativo cliente para assinar o JWT que é enviado ao servidor de autorização durante a solicitação de token. +_clientSecretJwtSigningAlgorithm (Opcional)_: Só é necessário quando `tokenEndpointAuthMethod` é `client_secret_jwt`. O algoritmo de assinatura JWT do client secret é usado pelo aplicativo cliente para assinar o JWT que é enviado ao servidor de autorização durante a solicitação de token. -_scope_: O parâmetro de escopo é usado para especificar o conjunto de recursos e permissões que o aplicativo cliente está solicitando acesso. O parâmetro de escopo é tipicamente definido como uma lista de valores separados por espaço que representam permissões específicas. Por exemplo, um valor de escopo de "read write" pode indicar que o aplicativo cliente está solicitando acesso de leitura e escrita aos dados de um usuário. +_scope_: O parâmetro scope é usado para especificar o conjunto de recursos e permissões que o aplicativo cliente está solicitando acesso. O parâmetro scope é normalmente definido como uma lista de valores separados por espaço que representam permissões específicas. Por exemplo, um valor de escopo "read write" pode indicar que o aplicativo cliente está solicitando acesso de leitura e escrita aos dados de um usuário. -Espera-se que você encontre `authorizationEndpoint`, `tokenEndpoint` e `userInfoEndpoint` na documentação do fornecedor social. +Você deve encontrar `authorizationEndpoint`, `tokenEndpoint` e `userInfoEndpoint` na documentação do fornecedor social. -_authenticationEndpoint_: Este endpoint é usado para iniciar o processo de autenticação. O processo de autenticação geralmente envolve o usuário fazer login e conceder autorização para que o aplicativo cliente acesse seus recursos. +_authenticationEndpoint_: Este endpoint é usado para iniciar o processo de autenticação. O processo de autenticação normalmente envolve o usuário fazendo login e concedendo autorização para o aplicativo cliente acessar seus recursos. -_tokenEndpoint_: Este endpoint é usado pelo aplicativo cliente para obter um token de acesso que pode ser usado para acessar os recursos solicitados. O aplicativo cliente geralmente envia uma solicitação ao endpoint de token com um tipo de concessão e código de autorização para receber um token de acesso. +_tokenEndpoint_: Este endpoint é usado pelo aplicativo cliente para obter um token de acesso que pode ser usado para acessar os recursos solicitados. O aplicativo cliente normalmente envia uma solicitação ao endpoint de token com um tipo de concessão e código de autorização para receber um token de acesso. -_userInfoEndpoint_: Este endpoint é usado pelo aplicativo cliente para obter informações adicionais sobre o usuário, como seu nome completo, endereço de email ou foto de perfil. O endpoint de informações do usuário é tipicamente acessado após o aplicativo cliente ter obtido um token de acesso do endpoint de token. +_userInfoEndpoint_: Este endpoint é usado pelo aplicativo cliente para obter informações adicionais sobre o usuário, como nome completo, endereço de e-mail ou foto de perfil. O endpoint de informações do usuário normalmente é acessado após o aplicativo cliente obter um token de acesso do endpoint de token. -Logto também fornece um campo `profileMap` que os usuários podem personalizar o mapeamento dos perfis dos fornecedores sociais, que geralmente não são padrão. As chaves são nomes de campos de perfil de usuário padrão do Logto e os valores correspondentes devem ser nomes de campos dos perfis sociais. Na fase atual, o Logto só se preocupa com 'id', 'name', 'avatar', 'email' e 'phone' do perfil social, apenas 'id' é obrigatório e os outros são campos opcionais. +O Logto também fornece um campo `profileMap` que os usuários podem personalizar para mapear os perfis dos fornecedores sociais, que geralmente não são padronizados. As chaves são os nomes dos campos padrão do perfil de usuário do Logto e os valores correspondentes devem ser os nomes dos campos dos perfis sociais. No estágio atual, o Logto só se preocupa com 'id', 'name', 'avatar', 'email' e 'phone' do perfil social, sendo apenas 'id' obrigatório e os demais campos opcionais. -`responseType` e `grantType` podem ser SOMENTE valores FIXOS com o tipo de concessão de código de autorização, então os tornamos opcionais e os valores padrão serão preenchidos automaticamente. +`responseType` e `grantType` SÓ podem ser valores FIXOS com o tipo de concessão authorization code, então os tornamos opcionais e os valores padrão serão preenchidos automaticamente. -Por exemplo, você pode encontrar [resposta de perfil de usuário do Google](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) e, portanto, seu `profileMap` deve ser assim: +Por exemplo, você pode encontrar a [resposta do perfil de usuário do Google](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) e, portanto, seu `profileMap` deve ser assim: ```json { @@ -41,8 +41,8 @@ Por exemplo, você pode encontrar [resposta de perfil de usuário do Google](htt :::note -Fornecemos uma chave `customConfig` OPCIONAL para colocar seus parâmetros personalizados. -Cada provedor de identidade social pode ter sua própria variante no protocolo padrão OAuth. Se o provedor de identidade social desejado seguir estritamente o protocolo padrão OAuth, então você não precisa se preocupar com `customConfig`. +Fornecemos uma chave OPCIONAL `customConfig` para colocar seus parâmetros personalizados. +Cada provedor de identidade social pode ter sua própria variação no protocolo padrão OAuth. Se o seu provedor de identidade social desejado seguir estritamente o protocolo padrão OAuth, então você não precisa se preocupar com o `customConfig`. ::: @@ -69,3 +69,69 @@ Cada provedor de identidade social pode ter sua própria variante no protocolo p | avatar | string | false | avatar | | email | string | false | email | | phone | string | false | phone | + +## Configurações gerais \{#general-settings} + +Aqui estão algumas configurações gerais que não bloqueiam a conexão com seu provedor de identidade, mas podem afetar a experiência de autenticação do usuário final. + +### Nome e logo do botão social \{#social-button-name-and-logo} + +Se você deseja exibir um botão social na sua página de login, pode definir o **nome** e o **logo** (modo escuro e modo claro) do provedor de identidade social. Isso ajudará os usuários a reconhecerem a opção de login social. + +### Nome do provedor de identidade \{#identity-provider-name} + +Cada conector social possui um nome exclusivo de Provedor de Identidade (IdP) para diferenciar as identidades dos usuários. Enquanto conectores comuns usam um nome de IdP fixo, conectores personalizados exigem um valor exclusivo. Saiba mais sobre [nomes de IdP](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) para mais detalhes. + +### Sincronizar informações do perfil \{#sync-profile-information} + +No conector OAuth, você pode definir a política para sincronizar informações do perfil, como nomes de usuário e avatares. Escolha entre: + +- **Sincronizar apenas no cadastro**: As informações do perfil são buscadas uma vez quando o usuário faz login pela primeira vez. +- **Sempre sincronizar no login**: As informações do perfil são atualizadas toda vez que o usuário faz login. + +### Armazenar tokens para acessar APIs de terceiros (Opcional) \{#store-tokens-to-access-third-party-apis-optional} + +Se você deseja acessar as APIs do Provedor de Identidade e realizar ações com autorização do usuário (seja via login social ou vinculação de conta), o Logto precisa obter escopos de API específicos e armazenar tokens. + +1. Adicione os escopos necessários no campo **scope** seguindo as instruções acima +2. Ative **Armazenar tokens para acesso persistente à API** no conector OAuth do Logto. O Logto armazenará tokens de acesso com segurança no Cofre de Segredos. +3. Para provedores de identidade OAuth/OIDC **padrão**, o escopo `offline_access` deve ser incluído para obter um token de atualização, evitando solicitações repetidas de consentimento do usuário. + +:::warning +Mantenha seu client secret seguro e nunca o exponha em código do lado do cliente. Se for comprometido, gere um novo imediatamente nas configurações do aplicativo do seu provedor de identidade. +::: + +## Utilize o conector OAuth \{#utilize-the-oauth-connector} + +Depois de criar um conector OAuth e conectá-lo ao seu provedor de identidade, você pode incorporá-lo aos seus fluxos de usuário final. Escolha as opções que atendem às suas necessidades: + +### Ativar botão de login social \{#enable-social-sign-in-button} + +1. No Logto Console, vá para Experiência de login > Cadastro e login. +2. Adicione o conector OAuth na seção **Login social** para permitir que os usuários se autentiquem com seu provedor de identidade. + +Saiba mais sobre a [experiência de login social](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular ou desvincular uma conta social \{#link-or-unlink-a-social-account} + +Use a Account API para construir um Centro de Conta personalizado em seu aplicativo que permita aos usuários autenticados vincular ou desvincular suas contas sociais. [Siga o tutorial da Account API](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +É permitido ativar o conector OAuth apenas para vinculação de conta e acesso à API, sem ativá-lo para login social. +::: + +### Acessar APIs do provedor de identidade e realizar ações \{#access-identity-provider-apis-and-perform-actions} + +Seu aplicativo pode recuperar tokens de acesso armazenados no Cofre de Segredos para chamar as APIs do seu provedor de identidade e automatizar tarefas de backend. As capacidades específicas dependem do seu provedor de identidade e dos escopos solicitados. Consulte o guia sobre como recuperar tokens armazenados para acesso à API. + +## Gerenciar a identidade social do usuário \{#manage-user-s-social-identity} + +Depois que um usuário vincula sua conta social, os administradores podem gerenciar essa conexão no Logto Console: + +1. Navegue até Logto console > Gerenciamento de usuários e abra o perfil do usuário. +2. Em **Conexões sociais**, localize o item do provedor de identidade e clique em **Gerenciar**. +3. Nesta página, os administradores podem gerenciar a conexão social do usuário, ver todas as informações de perfil concedidas e sincronizadas da conta social e verificar o status do token de acesso. + +:::note +Algumas respostas de token de acesso do Provedor de Identidade não incluem informações específicas de escopo, então o Logto não pode exibir diretamente a lista de permissões concedidas pelo usuário. No entanto, desde que o usuário tenha consentido com os escopos solicitados durante a autorização, seu aplicativo terá as permissões correspondentes ao acessar a API OAuth. +::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index feb0aca2cee..bb6ff81c20d 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -4,26 +4,36 @@ sidebar_label: OIDC (Social) sidebar_custom_props: description: OpenID Connect 1.0 é uma camada de identidade simples sobre o protocolo OAuth 2.0. tutorial_name: OIDC -tutorial_config_name: Aplicativo OIDC padrão +tutorial_config_name: Standard OIDC app --- import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# Configurar login social com OpenID Connect (OIDC) +# Configurar login social com OpenID Connect (OIDC) (Set up social login with OpenID Connect (OIDC)) O conector oficial do Logto para o protocolo OpenID Connect (OIDC). -## Introdução \{#get-started} +## Primeiros passos \{#get-started} -O conector OIDC permite a conexão do Logto a um provedor de identidade social arbitrário que suporta o protocolo OIDC. +O conector OIDC permite a conexão do Logto com qualquer provedor de identidade social que suporte o protocolo OIDC. Use o conector OIDC para permitir que seu aplicativo: + +- Adicione botões de login social +- Vincule contas de usuário a identidades sociais +- Sincronize informações do perfil do usuário a partir do provedor social +- Acesse APIs de terceiros por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas de automação (por exemplo, editar Google Docs, gerenciar eventos do Calendar em seu app) + +Para configurar esses recursos de autenticação, crie primeiro um conector OIDC no Logto: + +1. Vá para Console do Logto > Conector > Conector social. +2. Clique em **Adicionar conector social**, selecione **OIDC**, clique em **Próximo** e siga o tutorial passo a passo para concluir a integração. :::note -O conector OIDC é um tipo especial de conector no Logto, você pode adicionar alguns conectores baseados em OIDC. +O conector OIDC é um tipo especial de conector no Logto, você pode adicionar vários conectores baseados no protocolo OIDC. ::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index 32315367695..800e8f01b39 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,45 +1,45 @@ ## Crie seu aplicativo OIDC \{#create-your-oidc-app} -Ao abrir esta página, acreditamos que você já sabe qual provedor de identidade social deseja conectar. A primeira coisa a fazer é confirmar que o provedor de identidade suporta o protocolo OIDC, que é um pré-requisito para configurar um conector válido. Em seguida, siga as instruções do provedor de identidade para registrar e criar o aplicativo relevante para autorização OIDC. +Ao abrir esta página, acreditamos que você já sabe qual provedor de identidade social deseja conectar. A primeira coisa a fazer é confirmar se o provedor de identidade suporta o protocolo OIDC, que é um pré-requisito para configurar um conector válido. Em seguida, siga as instruções do provedor de identidade para registrar e criar o aplicativo relevante para autorização OIDC. ## Configure seu conector \{#configure-your-connector} -Nós SOMENTE suportamos o tipo de concessão "Authorization Code" por questões de segurança e ele se encaixa perfeitamente no cenário do Logto. +SOMENTE suportamos o tipo de concessão "Authorization Code" por questões de segurança e ele se encaixa perfeitamente no cenário do Logto. -`clientId` e `clientSecret` podem ser encontrados na página de detalhes dos seus aplicativos OIDC. +`clientId` e `clientSecret` podem ser encontrados na página de detalhes do seu aplicativo OIDC. -_clientId_: O ID do cliente é um identificador único que identifica o aplicativo cliente durante o registro com o servidor de autorização. Este ID é usado pelo servidor de autorização para verificar a identidade do aplicativo cliente e associar quaisquer tokens de acesso autorizados a esse aplicativo cliente específico. +_clientId_: O client ID é um identificador único que identifica o aplicativo cliente durante o registro com o servidor de autorização. Este ID é usado pelo servidor de autorização para verificar a identidade do aplicativo cliente e associar quaisquer tokens de acesso autorizados a esse aplicativo específico. -_clientSecret_: O segredo do cliente é uma chave confidencial emitida para o aplicativo cliente pelo servidor de autorização durante o registro. O aplicativo cliente usa essa chave secreta para se autenticar com o servidor de autorização ao solicitar tokens de acesso. O segredo do cliente é considerado informação confidencial e deve ser mantido seguro o tempo todo. +_clientSecret_: O client secret é uma chave confidencial emitida para o aplicativo cliente pelo servidor de autorização durante o registro. O aplicativo cliente usa essa chave secreta para se autenticar com o servidor de autorização ao solicitar tokens de acesso. O client secret é considerado informação confidencial e deve ser mantido seguro o tempo todo. -_tokenEndpointAuthMethod_: O método de autenticação do endpoint de token é usado pelo aplicativo cliente para se autenticar com o servidor de autorização ao solicitar tokens de acesso. Para descobrir métodos suportados, consulte o campo `token_endpoint_auth_methods_supported` disponível no endpoint de descoberta do OpenID Connect do provedor de serviços OAuth 2.0, ou consulte a documentação relevante fornecida pelo provedor de serviços OAuth 2.0. +_tokenEndpointAuthMethod_: O método de autenticação do endpoint de token é usado pelo aplicativo cliente para se autenticar com o servidor de autorização ao solicitar tokens de acesso. Para descobrir os métodos suportados, consulte o campo `token_endpoint_auth_methods_supported` disponível no endpoint de descoberta OpenID Connect do provedor de serviço OAuth 2.0, ou consulte a documentação relevante fornecida pelo provedor de serviço OAuth 2.0. -_clientSecretJwtSigningAlgorithm (Opcional)_: Apenas necessário quando `tokenEndpointAuthMethod` é `client_secret_jwt`. O algoritmo de assinatura JWT do segredo do cliente é usado pelo aplicativo cliente para assinar o JWT que é enviado ao servidor de autorização durante a solicitação de token. +_clientSecretJwtSigningAlgorithm (Opcional)_: Só é necessário quando `tokenEndpointAuthMethod` é `client_secret_jwt`. O algoritmo de assinatura JWT do client secret é usado pelo aplicativo cliente para assinar o JWT que é enviado ao servidor de autorização durante a solicitação de token. -_scope_: O parâmetro de escopo é usado para especificar o conjunto de recursos e permissões que o aplicativo cliente está solicitando acesso. O parâmetro de escopo é tipicamente definido como uma lista de valores separados por espaço que representam permissões específicas. Por exemplo, um valor de escopo de "read write" pode indicar que o aplicativo cliente está solicitando acesso de leitura e escrita aos dados de um usuário. +_scope_: O parâmetro scope é usado para especificar o conjunto de recursos e permissões que o aplicativo cliente está solicitando acesso. O parâmetro scope é normalmente definido como uma lista de valores separados por espaço que representam permissões específicas. Por exemplo, um valor de escopo "read write" pode indicar que o aplicativo cliente está solicitando acesso de leitura e escrita aos dados de um usuário. -Espera-se que você encontre `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` e `issuer` como informações de configuração do Provedor OpenID. Eles devem estar disponíveis na documentação do fornecedor social. +Você deve encontrar `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` e `issuer` como informações de configuração do OpenID Provider. Eles devem estar disponíveis na documentação do fornecedor social. -_authenticationEndpoint_: Este endpoint é usado para iniciar o processo de autenticação. O processo de autenticação geralmente envolve o usuário fazer login e conceder autorização para que o aplicativo cliente acesse seus recursos. +_authenticationEndpoint_: Este endpoint é usado para iniciar o processo de autenticação. O processo de autenticação normalmente envolve o usuário fazendo login e concedendo autorização para o aplicativo cliente acessar seus recursos. -_tokenEndpoint_: Este endpoint é usado pelo aplicativo cliente para obter um token de ID que pode ser usado para acessar os recursos solicitados. O aplicativo cliente geralmente envia uma solicitação ao endpoint de token com um tipo de concessão e código de autorização para receber um token de ID. +_tokenEndpoint_: Este endpoint é usado pelo aplicativo cliente para obter um token de ID que pode ser usado para acessar os recursos solicitados. O aplicativo cliente normalmente envia uma solicitação ao endpoint de token com um tipo de concessão e código de autorização para receber um token de ID. -_jwksUri_: Este é o endpoint URL onde o Conjunto de Chaves da Web JSON (JWKS) do provedor de identidade social (abreviado como IdP) pode ser obtido. O JWKS é um conjunto de chaves criptográficas que o IdP usa para assinar e verificar JSON Web Tokens (JWTs) que são emitidos durante o processo de autenticação. O `jwksUri` é usado pela parte confiável (RP) para obter as chaves públicas usadas pelo IdP para assinar os JWTs, para que a RP possa verificar a autenticidade e integridade dos JWTs recebidos do IdP. +_jwksUri_: Esta é a URL do endpoint onde o JSON Web Key Set (JWKS) do provedor de identidade social (IdP) pode ser obtido. O JWKS é um conjunto de chaves criptográficas que o IdP usa para assinar e verificar JSON Web Tokens (JWTs) emitidos durante o processo de autenticação. O `jwksUri` é usado pela relying party (RP) para obter as chaves públicas usadas pelo IdP para assinar os JWTs, para que a RP possa verificar a autenticidade e integridade dos JWTs recebidos do IdP. -_issuer_: Este é o identificador único do IdP que é usado pela RP para verificar os JWTs recebidos do IdP. Ele é incluído nos JWTs como a [reivindicação](https://www.rfc-editor.org/rfc/rfc7519#section-4) `iss` (o token de ID é sempre um JWT). O valor do emissor deve corresponder ao URL do servidor de autorização do IdP e deve ser um URI que a RP confia. Quando a RP recebe um JWT, ela verifica a reivindicação `iss` para garantir que foi emitido por um IdP confiável e que o JWT é destinado ao uso com a RP. +_issuer_: Este é o identificador único do IdP que é usado pela RP para verificar os JWTs recebidos do IdP. Ele é incluído nos JWTs como a [reivindicação (Claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4) `iss` (o token de ID é sempre um JWT). O valor do issuer deve corresponder à URL do servidor de autorização do IdP, e deve ser um URI que a RP confia. Quando a RP recebe um JWT, ela verifica a reivindicação `iss` para garantir que foi emitido por um IdP confiável e que o JWT se destina ao uso com a RP. -Juntos, `jwksUri` e `issuer` fornecem um mecanismo seguro para a RP verificar a identidade do usuário final durante o processo de autenticação. Usando as chaves públicas obtidas do `jwksUri`, a RP pode verificar a autenticidade e integridade dos JWTs emitidos pelo IdP. O valor do emissor garante que a RP apenas aceite JWTs que foram emitidos por um IdP confiável e que os JWTs são destinados ao uso com a RP. +Juntos, `jwksUri` e `issuer` fornecem um mecanismo seguro para a RP verificar a identidade do usuário final durante o processo de autenticação. Usando as chaves públicas obtidas do `jwksUri`, a RP pode verificar a autenticidade e integridade dos JWTs emitidos pelo IdP. O valor do issuer garante que a RP só aceite JWTs emitidos por um IdP confiável e que os JWTs se destinam ao uso com a RP. -Como uma solicitação de autenticação é sempre necessária, um `authRequestOptionalConfig` é fornecido para encapsular todas as configurações opcionais, você pode encontrar detalhes em [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Você também pode notar que `nonce` está ausente nesta configuração. Como `nonce` deve ser idêntico para cada solicitação, colocamos a geração de `nonce` na implementação do código. Então, não se preocupe com isso! O anteriormente mencionado `jwksUri` e `issuer` também estão incluídos em `idTokenVerificationConfig`. +Como uma solicitação de autenticação é sempre necessária, um `authRequestOptionalConfig` é fornecido para agrupar todas as configurações opcionais. Você pode encontrar detalhes em [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Você também pode notar que `nonce` está ausente nesta configuração. Como o `nonce` deve ser idêntico para cada solicitação, colocamos a geração do `nonce` na implementação do código. Portanto, não se preocupe com isso! Os já mencionados `jwksUri` e `issuer` também estão incluídos em `idTokenVerificationConfig`. -Você pode estar curioso sobre por que um protocolo OIDC padrão suporta tanto os fluxos implícitos quanto híbridos, mas o conector Logto suporta apenas o fluxo de autorização. Foi determinado que os fluxos implícitos e híbridos são menos seguros do que o fluxo de autorização. Devido ao foco do Logto na segurança, ele suporta apenas o fluxo de autorização para o mais alto nível de segurança para seus usuários, apesar de sua natureza ligeiramente menos conveniente. +Você pode estar curioso sobre o motivo de um protocolo OIDC padrão suportar tanto os fluxos implícito quanto híbrido, mas o conector Logto suporta apenas o fluxo de autorização. Foi determinado que os fluxos implícito e híbrido são menos seguros do que o fluxo de autorização. Devido ao foco do Logto em segurança, ele suporta apenas o fluxo de autorização para garantir o mais alto nível de segurança para seus usuários, apesar de ser um pouco menos conveniente. -`responseType` e `grantType` podem ser SOMENTE valores FIXOS com o fluxo "Authorization Code", então os tornamos opcionais e os valores padrão serão preenchidos automaticamente. +`responseType` e `grantType` só podem ser valores FIXOS com o fluxo "Authorization Code", então os tornamos opcionais e os valores padrão serão preenchidos automaticamente. :::note -Para todos os tipos de fluxo, fornecemos uma chave `customConfig` OPCIONAL para colocar seus parâmetros personalizados. -Cada provedor de identidade social pode ter sua própria variante no protocolo padrão OIDC. Se o provedor de identidade social desejado seguir estritamente o protocolo padrão OIDC, então você não precisa se preocupar com `customConfig`. +Para todos os tipos de fluxo, fornecemos uma chave OPCIONAL `customConfig` para colocar seus parâmetros personalizados. +Cada provedor de identidade social pode ter sua própria variante do protocolo padrão OIDC. Se o seu provedor de identidade social desejado seguir estritamente o protocolo padrão OIDC, então você não precisa se preocupar com o `customConfig`. ::: @@ -47,39 +47,105 @@ Cada provedor de identidade social pode ter sua própria variante no protocolo p | Nome | Tipo | Obrigatório | | ------------------------- | ------------------------- | ----------- | -| scope | string | True | -| clientId | string | True | -| clientSecret | string | True | -| authorizationEndpoint | string | True | -| tokenEndpoint | string | True | -| idTokenVerificationConfig | IdTokenVerificationConfig | True | -| authRequestOptionalConfig | AuthRequestOptionalConfig | False | -| customConfig | Record\ | False | +| scope | string | Sim | +| clientId | string | Sim | +| clientSecret | string | Sim | +| authorizationEndpoint | string | Sim | +| tokenEndpoint | string | Sim | +| idTokenVerificationConfig | IdTokenVerificationConfig | Sim | +| authRequestOptionalConfig | AuthRequestOptionalConfig | Não | +| customConfig | Record\ | Não | | Propriedades de AuthRequestOptionalConfig | Tipo | Obrigatório | | ----------------------------------------- | ------ | ----------- | -| responseType | string | False | -| tokenEndpoint | string | False | -| responseMode | string | False | -| display | string | False | -| prompt | string | False | -| maxAge | string | False | -| uiLocales | string | False | -| idTokenHint | string | False | -| loginHint | string | False | -| acrValues | string | False | +| responseType | string | Não | +| tokenEndpoint | string | Não | +| responseMode | string | Não | +| display | string | Não | +| prompt | string | Não | +| maxAge | string | Não | +| uiLocales | string | Não | +| idTokenHint | string | Não | +| loginHint | string | Não | +| acrValues | string | Não | | Propriedades de IdTokenVerificationConfig | Tipo | Obrigatório | | ----------------------------------------- | ---------------------------------- | ----------- | -| jwksUri | string | True | -| issuer | string \| string[] | False | -| audience | string \| string[] | False | -| algorithms | string[] | False | -| clockTolerance | string \| number | False | -| crit | Record\ | False | -| currentDate | Date | False | -| maxTokenAge | string \| number | False | -| subject | string | False | -| typ | string | False | - -Veja [aqui](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) para encontrar mais detalhes sobre `IdTokenVerificationConfig`. +| jwksUri | string | Sim | +| issuer | string \| string[] | Não | +| audience | string \| string[] | Não | +| algorithms | string[] | Não | +| clockTolerance | string \| number | Não | +| crit | Record\ | Não | +| currentDate | Date | Não | +| maxTokenAge | string \| number | Não | +| subject | string | Não | +| typ | string | Não | + +Veja [aqui](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) para mais detalhes sobre `IdTokenVerificationConfig`. + +## Configurações gerais \{#general-settings} + +Aqui estão algumas configurações gerais que não bloqueiam a conexão com seu provedor de identidade, mas podem afetar a experiência de autenticação do usuário final. + +### Nome e logo do botão social \{#social-button-name-and-logo} + +Se você deseja exibir um botão social em sua página de login, pode definir o **nome** e o **logo** (modo escuro e modo claro) do provedor de identidade social. Isso ajudará os usuários a reconhecerem a opção de login social. + +### Nome do provedor de identidade \{#identity-provider-name} + +Cada conector social possui um nome exclusivo de Provedor de Identidade (IdP) para diferenciar as identidades dos usuários. Enquanto conectores comuns usam um nome de IdP fixo, conectores personalizados exigem um valor exclusivo. Saiba mais sobre [nomes de IdP](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name) para mais detalhes. + +### Sincronizar informações de perfil \{#sync-profile-information} + +No conector OIDC, você pode definir a política para sincronizar informações de perfil, como nomes de usuário e avatares. Escolha entre: + +- **Sincronizar apenas no cadastro**: As informações do perfil são buscadas uma vez quando o usuário faz login pela primeira vez. +- **Sempre sincronizar no login**: As informações do perfil são atualizadas toda vez que o usuário faz login. + +### Armazenar tokens para acessar APIs de terceiros (Opcional) \{#store-tokens-to-access-third-party-apis-optional} + +Se você deseja acessar as APIs do Provedor de Identidade e realizar ações com autorização do usuário (seja via login social ou vinculação de conta), o Logto precisa obter escopos de API específicos e armazenar tokens. + +1. Adicione os escopos necessários no campo **scope** seguindo as instruções acima +2. Ative **Armazenar tokens para acesso persistente à API** no conector OIDC do Logto. O Logto armazenará tokens de acesso com segurança no Cofre de Segredos. +3. Para provedores de identidade OAuth/OIDC **padrão**, o escopo `offline_access` deve ser incluído para obter um token de atualização, evitando solicitações repetidas de consentimento do usuário. + +:::warning +Mantenha seu client secret seguro e nunca o exponha em código do lado do cliente. Se for comprometido, gere um novo imediatamente nas configurações do aplicativo do seu provedor de identidade. +::: + +## Utilize o conector OIDC \{#utilize-the-oidc-connector} + +Depois de criar um conector OIDC e conectá-lo ao seu provedor de identidade, você pode incorporá-lo aos seus fluxos de usuário final. Escolha as opções que correspondem às suas necessidades: + +### Ativar botão de login social \{#enable-social-sign-in-button} + +1. No Logto Console, vá para Experiência de login > Cadastro e login. +2. Adicione o conector OIDC na seção **Login social** para permitir que os usuários se autentiquem com seu provedor de identidade. + +Saiba mais sobre [experiência de login social](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in). + +### Vincular ou desvincular uma conta social \{#link-or-unlink-a-social-account} + +Use a Account API para criar um Centro de Conta personalizado em seu aplicativo que permita aos usuários autenticados vincular ou desvincular suas contas sociais. [Siga o tutorial da Account API](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +É permitido ativar o conector OIDC apenas para vinculação de conta e acesso à API, sem ativá-lo para login social. +::: + +### Acessar APIs do provedor de identidade e realizar ações \{#access-identity-provider-apis-and-perform-actions} + +Seu aplicativo pode recuperar tokens de acesso armazenados no Cofre de Segredos para chamar as APIs do seu provedor de identidade e automatizar tarefas de backend. As capacidades específicas dependem do seu provedor de identidade e dos escopos solicitados. Consulte o guia sobre como recuperar tokens armazenados para acesso à API. + +## Gerenciar a identidade social do usuário \{#manage-user-s-social-identity} + +Depois que um usuário vincula sua conta social, os administradores podem gerenciar essa conexão no Logto Console: + +1. Navegue até Logto console > Gerenciamento de usuários e abra o perfil do usuário. +2. Em **Conexões sociais**, localize o item do provedor de identidade e clique em **Gerenciar**. +3. Nesta página, os administradores podem gerenciar a conexão social do usuário, ver todas as informações de perfil concedidas e sincronizadas da conta social e verificar o status do token de acesso. + +:::note +Algumas respostas de token de acesso do Provedor de Identidade não incluem informações específicas de escopo, então o Logto não pode exibir diretamente a lista de permissões concedidas pelo usuário. No entanto, desde que o usuário tenha consentido com os escopos solicitados durante a autorização, seu aplicativo terá as permissões correspondentes ao acessar a API OIDC. +::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index 54240ddac8d..eb59c43fc9b 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -16,33 +16,38 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; # Configurar Single Sign-On com Google Workspace -Com esforços mínimos de configuração, este conector permite a integração com o Microsoft Entra ID para SSO corporativo. +Com um esforço mínimo de configuração, este conector permite a integração com o Microsoft Entra ID para SSO corporativo (Enterprise SSO). -## Etapa 1: Criar um novo projeto no Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} +## Passo 1: Crie um novo projeto no Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} -## Etapa 2: Configurar a tela de consentimento para seu aplicativo \{#step-2-config-the-consent-screen-for-your-application} +## Passo 2: Configure a tela de consentimento para seu aplicativo \{#step-2-config-the-consent-screen-for-your-application} -## Etapa 3: Criar uma nova credencial OAuth \{#step-3-create-a-new-oauth-credential} +## Passo 3: Crie uma nova credencial OAuth \{#step-3-create-a-new-oauth-credential} -## Etapa 4: Configurar o conector Logto com as credenciais do cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} +## Passo 4: Configure o conector Logto com as credenciais do cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} -## Etapa 5: Escopos adicionais (Opcional) \{#step-5-additional-scopes-optional} +## Passo 5: Escopos adicionais (Opcional) \{#step-5-additional-scopes-optional} -## Etapa 6: Definir domínios de email e habilitar o conector SSO \{#step-6-set-email-domains-and-enable-the-sso-connector} +## Passo 6: Armazene tokens para acessar APIs do Google (Opcional) \{#step-6-store-tokens-to-access-google-apis-optional} + +## Passo 7: Defina domínios de e-mail e habilite o conector SSO \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index 69167a3edcb..5d7e02ff7ef 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,27 +4,32 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -### Etapa 1: Criar um novo projeto no Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} +### Etapa 1: Crie um novo projeto no Google Cloud Platform \{#step-1-create-a-new-project-on-google-cloud-platform} -### Etapa 2: Configurar a tela de consentimento para seu aplicativo \{#step-2-config-the-consent-screen-for-your-application} +### Etapa 2: Configure a tela de consentimento para seu aplicativo \{#step-2-config-the-consent-screen-for-your-application} -### Etapa 3: Criar uma nova credencial OAuth \{#step-3-create-a-new-oauth-credential} +### Etapa 3: Crie uma nova credencial OAuth \{#step-3-create-a-new-oauth-credential} -### Etapa 4: Configurar o conector Logto com as credenciais do cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} +### Etapa 4: Configure o conector Logto com as credenciais do cliente \{#step-4-set-up-logto-connector-with-the-client-credentials} -### Etapa 5: Escopos adicionais (Opcional) \{#step-5-additional-scopes-optional} +### Etapa 5: Escopos adicionais (opcional) \{#step-5-additional-scopes-optional} -### Etapa 6: Definir domínios de email e habilitar o conector SSO \{#step-6-set-email-domains-and-enable-the-sso-connector} +### Etapa 6: Armazene tokens para acessar as APIs do Google (opcional) \{#step-6-store-tokens-to-access-google-apis-optional} + +### Etapa 7: Defina domínios de e-mail e habilite o conector SSO \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index c128a50c21c..67354166856 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -Use o campo `Scope` para adicionar escopos adicionais à sua solicitação OAuth. Isso permitirá que você solicite mais informações do servidor OAuth do Google. Consulte a documentação [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) para mais informações. +Escopos definem as permissões que seu aplicativo solicita dos usuários e controlam quais dados seu aplicativo pode acessar nas contas Google Workspace deles. Solicitar permissões do Google requer configuração em ambos os lados: -Independentemente das configurações de escopo personalizadas, o Logto sempre enviará os escopos `openid`, `profile` e `email` para o IdP. Isso é para garantir que o Logto possa recuperar corretamente as informações de identidade e o endereço de email do usuário. +**No Google Cloud Console:** + +1. Navegue até **APIs & Services > OAuth consent screen > Scopes**. +2. Clique em **Add or Remove Scopes** e selecione apenas os escopos que seu aplicativo necessita: + - Autenticação (Authentication) (Obrigatório): + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - Acesso à API (Opcional): Adicione quaisquer escopos adicionais necessários para seu aplicativo (por exemplo, Drive, Calendar, YouTube). Navegue pela [Google API Library](https://console.cloud.google.com/apis/library) para encontrar os serviços disponíveis. Se seu aplicativo precisar de acesso às APIs do Google além das permissões básicas, primeiro ative as APIs específicas que seu aplicativo usará (por exemplo, Google Drive API, Gmail API, Calendar API) na Google API Library. +3. Clique em **Update** para confirmar a seleção. +4. Clique em **Save and Continue** para aplicar as alterações. + +**No conector Google Workspace do Logto:** + +1. O Logto inclui automaticamente os escopos `openid`, `profile` e `email` para recuperar informações básicas de identidade do usuário. Você pode deixar o campo `Scopes` em branco se precisar apenas das informações básicas do usuário. +2. Adicione escopos adicionais (separados por espaços) no campo `Scopes` para solicitar mais dados do Google. Use URLs completas dos escopos, por exemplo: `https://www.googleapis.com/auth/calendar.readonly` + +:::tip +Se seu aplicativo solicitar esses escopos para acessar a API do Google e realizar ações, certifique-se de habilitar **Store tokens for persistent API access** no conector Google do Logto. Veja a próxima seção para detalhes. +::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index 172cd0982bf..158dec996e4 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -Forneça os `domínios de email` da sua organização na aba `SSO experience` do conector do Logto. Isso habilitará o conector SSO como um método de autenticação para esses usuários. +Se você deseja acessar as [APIs do Google](https://console.cloud.google.com/apis/library) e realizar ações com autorização do usuário, o Logto precisa obter escopos de API específicos e armazenar tokens. -Usuários com endereços de email nos domínios especificados serão redirecionados para usar seu conector SSO como seu único método de autenticação. +1. Adicione os escopos necessários na configuração da tela de consentimento OAuth do Google Cloud Console e no conector Google do Logto. +2. Ative **Armazenar tokens para acesso persistente à API** no conector Google do Logto. O Logto armazenará com segurança os tokens de acesso e atualização do Google no Cofre de Segredos (Secret Vault). +3. Para garantir que os tokens de atualização sejam retornados, configure seu conector Google do Logto para habilitar o **Acesso offline (Offline Access)**. -Para mais informações sobre o conector SSO do Google Workspace, por favor, consulte [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). +:::warning +Você não precisa adicionar `offline_access` no campo `Scope` do Logto — fazer isso pode causar um erro. O Google usa `access_type=offline` automaticamente quando o acesso offline está habilitado. +::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..251f1410cac --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +Forneça os `domínios de email` da sua organização na guia `Experiência SSO (SSO experience)` do conector do Logto. Isso habilitará o conector SSO como um método de autenticação para esses usuários. + +Usuários com endereços de email nos domínios especificados serão redirecionados para usar seu conector SSO como seu único método de autenticação. + +Para mais informações sobre o conector SSO do Google Workspace, consulte [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect). diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index cee9c818bba..0de6efb85fa 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -2,10 +2,10 @@ slug: /integrations/oidc-sso sidebar_label: OIDC (Enterprise) sidebar_custom_props: - description: Protocolo moderno construído sobre OAuth 2.0 para verificação de identidade em aplicativos web e móveis. + description: Protocolo moderno construído sobre OAuth 2.0 para verificação de identidade em aplicativos web e mobile. logoFilename: 'oidc.svg' tutorial_name: OIDC enterprise SSO -tutorial_config_name: Aplicativo OIDC no seu IdP +tutorial_config_name: OIDC application on your IdP --- import GuideTip from '../../fragments/_sso_guide_tip.mdx'; @@ -13,21 +13,31 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; # Configurar Single Sign-On com OpenID Connect (OIDC) -Com esforços mínimos de configuração, este conector permite a integração com qualquer Provedor de Identidade (IdP) baseado em OIDC. +Com um esforço mínimo de configuração, este conector permite a integração com qualquer Provedor de Identidade (IdP) baseado em OIDC. -## Passo 1: Criar um aplicativo OIDC no seu IdP \{#step-1-create-an-oidc-application-on-your-idp} +## Passo 1: Crie uma aplicação OIDC no seu IdP \{#step-1-create-an-oidc-application-on-your-idp} -## Passo 2: Configurar OIDC SSO no Logto \{#step-2-configure-oidc-sso-on-logto} +## Passo 2: Configure o SSO OIDC no Logto \{#step-2-configure-oidc-sso-on-logto} -## Passo 3: Definir domínios de email e habilitar o conector SSO \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Passo 3: Configure escopos (Opcional) \{#step-3-configure-scopes-optional} + +## Passo 4: Armazene tokens para acessar APIs de terceiros (Opcional) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Passo 5: Defina domínios de e-mail e habilite o conector SSO \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index a79b04c1f3f..b7cc70ef106 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,15 +1,25 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; -### Etapa 1: Criar um aplicativo OIDC no seu IdP \{#step-1-create-an-oidc-application-on-your-idp} +### Etapa 1: Crie um aplicativo OIDC no seu IdP \{#step-1-create-an-oidc-application-on-your-idp} -### Etapa 2: Configurar OIDC SSO no Logto \{#step-2-configure-oidc-sso-on-logto} +### Etapa 2: Configure o OIDC SSO no Logto \{#step-2-configure-oidc-sso-on-logto} -### Etapa 3: Definir domínios de email e habilitar o conector SSO \{#step-3-set-email-domains-and-enable-the-sso-connector} +## Etapa 3: Configure escopos (opcional) \{#step-3-configure-scopes-optional} + +## Etapa 4: Armazene tokens para acessar APIs de terceiros (opcional) \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## Etapa 5: Defina domínios de email e habilite o conector SSO \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index 7d38d47118a..5680209321a 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -Após criar com sucesso um aplicativo OIDC no lado do IdP, você precisará fornecer as configurações do IdP de volta para o Logto. Navegue até a aba `Connection` e preencha as seguintes configurações: +Após criar com sucesso um aplicativo OIDC no lado do provedor de identidade (IdP), você precisará fornecer as configurações do IdP de volta ao Logto. Navegue até a aba `Connection` e preencha as seguintes configurações: -- **Client ID**: Um identificador único atribuído ao seu aplicativo OIDC pelo IdP. Este identificador é usado pelo Logto para identificar e autenticar o aplicativo durante o fluxo OIDC. -- **Client Secret**: Um segredo confidencial compartilhado entre o Logto e o IdP. Este segredo é usado para autenticar o aplicativo OIDC e proteger a comunicação entre o Logto e o IdP. -- **Emissor (Issuer)**: A URL do emissor, um identificador único para o IdP, especificando a localização onde o provedor de identidade OIDC pode ser encontrado. É uma parte crucial da configuração OIDC, pois ajuda o Logto a descobrir os endpoints necessários. - Para facilitar o processo de configuração, o Logto buscará automaticamente os endpoints e configurações OIDC necessários. Isso é feito utilizando o emissor que você forneceu e fazendo uma chamada aos endpoints de descoberta OIDC do IdP. É imperativo garantir que o endpoint do emissor seja válido e configurado corretamente para permitir que o Logto recupere as informações necessárias corretamente. - Após uma solicitação de busca bem-sucedida, você deverá ver as configurações do IdP analisadas na seção de emissores. -- **Escopo (Scope)**: Uma lista de strings separadas por espaços definindo as permissões ou níveis de acesso desejados solicitados pelo Logto durante o processo de autenticação OIDC. O parâmetro de escopo permite que você especifique quais informações e acessos o Logto está solicitando do IdP. - O parâmetro de escopo é opcional. Independentemente das configurações de escopo personalizadas, o Logto sempre enviará os escopos `openid`, `profile` e `email` para o IdP. - Isso é para garantir que o Logto possa recuperar corretamente as informações de identidade do usuário e o endereço de email do IdP. Você pode adicionar escopos adicionais ao parâmetro de escopo para solicitar mais informações do IdP. +- **Client ID**: Um identificador único atribuído ao seu aplicativo OIDC pelo IdP. Esse identificador é usado pelo Logto para identificar e autenticar o aplicativo durante o fluxo OIDC. +- **Client Secret**: Um segredo confidencial compartilhado entre o Logto e o IdP. Esse segredo é utilizado para autenticar o aplicativo OIDC e proteger a comunicação entre o Logto e o IdP. +- **Emissor (Issuer)**: A URL do emissor, um identificador único para o IdP, especificando o local onde o provedor de identidade OIDC pode ser encontrado. É uma parte crucial da configuração OIDC, pois ajuda o Logto a descobrir os endpoints necessários. + Para facilitar o processo de configuração, o Logto buscará automaticamente os endpoints e configurações OIDC necessários. Isso é feito utilizando o emissor fornecido e realizando uma chamada aos endpoints de descoberta OIDC do IdP. É fundamental garantir que o endpoint do emissor esteja válido e configurado corretamente para permitir que o Logto recupere as informações necessárias corretamente. + Após uma solicitação de busca bem-sucedida, você deverá conseguir visualizar as configurações do IdP analisadas na seção de emissores (issuers). diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index 89e9555d3f4..ccb579f55a6 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -Forneça os `domínios de email` da sua organização na aba `SSO experience` do conector do Logto. Isso habilitará o conector SSO como um método de autenticação para esses usuários. +Escopos (Scopes) definem as permissões que seu aplicativo solicita dos usuários e controlam quais dados seu aplicativo pode acessar das contas corporativas deles. -Usuários com endereços de email nos domínios especificados serão redirecionados para usar seu conector SSO como seu único método de autenticação. +Configurar escopos requer configuração em ambos os lados: + +1. **Seu Provedor de Identidade (IdP) (Identity Provider)**: Configure quais permissões são permitidas para autorização no console do seu IdP + - Alguns IdPs habilitam todos os escopos públicos por padrão (nenhuma ação necessária) + - Outros exigem que você conceda permissões explicitamente +2. **Conector corporativo Logto (Logto enterprise connector)**: Especifique quais escopos solicitar durante a autenticação nas configurações do conector OIDC corporativo do Logto > campo `Scopes`. + - O Logto sempre inclui os escopos `openid`, `profile` e `email` para recuperar informações básicas de identidade do usuário, independentemente das suas configurações de escopo personalizadas. + - Você pode adicionar escopos adicionais (separados por espaços) para solicitar mais informações do IdP. + +:::tip +Se seu aplicativo precisar acessar APIs usando esses escopos, certifique-se de habilitar **Armazenar tokens para acesso persistente à API (Store tokens for persistent API access)** no seu conector corporativo Logto. Veja a próxima seção para detalhes. +::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..62380568e19 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +Se você deseja acessar as APIs do Provedor de Identidade (Identity Provider) e realizar ações com autorização do usuário, o Logto precisa obter escopos de API (API scopes) específicos e armazenar tokens. + +1. Adicione os escopos necessários no campo **scope** seguindo as instruções acima +2. Ative **Armazenar tokens para acesso persistente à API** no conector empresarial OIDC do Logto. O Logto armazenará com segurança os tokens de acesso no Cofre de Segredos (Secret Vault). +3. Para provedores de identidade OIDC **padrão** (standard), o escopo `offline_access` deve ser incluído para obter um token de atualização (refresh token), evitando solicitações repetidas de consentimento do usuário. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..dc94ae203e9 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +Forneça os `domínios de email` da sua organização na guia `SSO experience` do conector do Logto. Isso habilitará o conector SSO como um método de autenticação para esses usuários. + +Usuários com endereços de email nos domínios especificados serão redirecionados para usar seu conector SSO como seu único método de autenticação. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index 2c45902dced..cec754c6964 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -4,43 +4,47 @@ sidebar_position: 2 # Implantação e configuração -No artigo anterior, abordamos o básico de [começar rapidamente com o Logto](/logto-oss/get-started-with-oss). Este artigo aprofunda, focando nas melhores práticas e etapas detalhadas de configuração para implantar o Logto em um ambiente de produção. +No artigo anterior, abordamos o básico de [como começar rapidamente com o Logto](/logto-oss/get-started-with-oss). Este artigo aprofunda mais, focando em melhores práticas e etapas detalhadas de configuração para implantar o Logto em um ambiente de produção. ## Variáveis de ambiente \{#environment-variables} -Usamos um conjunto gerado de variáveis de ambiente em nosso demo (`docker-compose.yml`), que você deve substituir pelas suas próprias e manter a consistência em várias instâncias do Logto. +Usamos um conjunto gerado de variáveis de ambiente em nosso demo (`docker-compose.yml`), que você deve substituir pelas suas próprias e manter a consistência entre múltiplas instâncias do Logto. -Você pode definir as variáveis de ambiente diretamente ou colocar um arquivo `.env` na raiz do projeto Logto. Se você estiver testando com Docker, verifique o `.env` gerado da imagem em `/etc/logto`. +Você pode definir as variáveis diretamente ou colocar um arquivo `.env` na raiz do projeto Logto. Se estiver testando com Docker, confira o `.env` gerado da imagem em `/etc/logto`. ### Essenciais \{#essentials} -- `DB_URL` O [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para o banco de dados Logto. +- `DB_URL` O [DSN do Postgres](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) para o banco de dados do Logto. - `PORT` A porta que o Logto escuta. Padrão `3001`. -- `ENDPOINT` Você pode especificar uma URL com seu domínio personalizado para produção (Ex.: `ENDPOINT=https://logto.domain.com`). Isso também afetará o valor do [identificador do emissor OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). +- `ENDPOINT` Você pode especificar uma URL com seu domínio personalizado para produção (Ex: `ENDPOINT=https://logto.domain.com`). Isso também afetará o valor do [identificador do emissor OIDC](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). -**Habilitar Console de Administração** +**Habilitar o Admin Console** -- `ADMIN_PORT` A porta que o Console de Administração do Logto escuta. Padrão `3002`. -- `ADMIN_ENDPOINT` Você pode especificar uma URL com seu domínio personalizado para produção (Ex.: `ADMIN_ENDPOINT=https://admin.domain.com`). Isso também afetará o valor dos URIs de Redirecionamento do Console de Administração. +- `ADMIN_PORT` A porta que o Logto Admin Console escuta. Padrão `3002`. +- `ADMIN_ENDPOINT` Você pode especificar uma URL com seu domínio personalizado para produção (Ex: `ADMIN_ENDPOINT=https://admin.domain.com`). Isso também afetará o valor dos URIs de redirecionamento do Admin Console. -**Desabilitar Console de Administração** +**Desabilitar o Admin Console** -- `ADMIN_DISABLE_LOCALHOST` Defina como `1` ou `true` para fechar a porta para o Console de Administração. Com `ADMIN_ENDPOINT` não definido, ele desativará completamente o Console de Administração. +- `ADMIN_DISABLE_LOCALHOST` Defina como `1` ou `true` para fechar a porta do Admin Console. Com `ADMIN_ENDPOINT` não definido, o Admin Console será completamente desabilitado. Para mais detalhes sobre variáveis de ambiente, veja [Configuração](/concepts/core-service/configuration/). +**Habilitar Secret Vault** + +- Para usar o [Secret Vault](/secret-vault), você precisa definir `SECRET_VAULT_KEK` como uma string codificada em base64 da sua Key Encryption Key (KEK). Isso é usado para criptografar as Data Encryption Keys (DEK) no Secret Vault. Recomenda-se AES-256 (32 bytes). Exemplo: `crypto.randomBytes(32).toString('base64')`. + ### HTTPS \{#https} Você pode usar Node.js para servir HTTPS diretamente ou configurar um proxy / balanceador HTTPS na frente do Node.js. Veja [Habilitando HTTPS](/concepts/core-service/configuration/#enabling-https) para detalhes. ### Proxy reverso \{#reverse-proxy} -Se você quiser usar proxy reverso no seu servidor, por exemplo, Nginx ou Apache, você precisa mapear as portas 3001 e 3002 separadamente nas configurações de passagem do proxy. Supondo que você esteja usando Nginx, seu endpoint de autenticação Logto está rodando na porta 3001, e seu console de administração Logto está rodando na 3002, coloque a seguinte configuração em nginx.conf: +Se você quiser usar proxy reverso em seu servidor, por exemplo Nginx ou Apache, você precisa mapear as portas 3001 e 3002 separadamente nas configurações de proxy pass. Supondo que você esteja usando Nginx, seu endpoint de autenticação Logto está rodando na porta 3001, e seu admin console Logto está rodando na 3002, coloque a seguinte configuração no nginx.conf: ``` server { listen 443 ssl; - server_name ; // e.g. auth.your-domain.com + server_name ; // ex: auth.seu-dominio.com ... location / { @@ -58,12 +62,12 @@ server { } ``` -Em seguida, adicione a configuração semelhante para o seu console de administração: +Depois adicione uma configuração similar para seu admin console: ``` server { listen 443 ssl; - server_name ; // e.g. admin.your-domain.com + server_name ; // ex: admin.seu-dominio.com ... location / { @@ -87,15 +91,15 @@ Recarregue a configuração do Nginx para aplicar as últimas alterações: nginx -s reload ``` -Tudo pronto. Abra o navegador e visite `https://admin.your-domain.com`, você deve conseguir ver a página de boas-vindas do Logto. +Tudo pronto. Abra o navegador e acesse `https://admin.seu-dominio.com`, você deverá ver a página de boas-vindas do Logto. ## Containerização \{#containerization} -Para produção, você pode usar Docker para containerizar o Logto. Você pode encontrar o Dockerfile no diretório raiz do projeto. Se você quiser executar várias instâncias do Logto, por exemplo, implantar o Logto em um cluster Kubernetes, há algumas etapas adicionais que você precisa seguir. +Para produção, você pode usar Docker para containerizar o Logto. Você encontra o Dockerfile no diretório raiz do projeto. Se quiser rodar múltiplas instâncias do Logto, por exemplo, implantar o Logto em um cluster Kubernetes, há alguns passos adicionais que você precisa seguir. ### Pasta de conectores compartilhada \{#shared-connectors-folder} -Por padrão, o Logto criará uma pasta `connectors` no diretório raiz da pasta `core`. Recomendamos compartilhar a pasta entre várias instâncias do Logto, você precisa montar a pasta `packages/core/connectors` no contêiner e executar `npm run cli connector add -- --official` para implantar os conectores. +Por padrão, o Logto criará uma pasta `connectors` no diretório raiz da pasta `core`. Recomendamos compartilhar essa pasta entre múltiplas instâncias do Logto; você precisa montar a pasta `packages/core/connectors` no container e rodar `npm run cli connector add -- --official` para implantar os conectores. Aqui está um exemplo mínimo de `deployment` para Kubernetes: @@ -130,19 +134,19 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -Neste exemplo, criamos um diretório vazio como um volume e o montamos nos contêineres. Em seguida, executamos `npm run cli connector add -- --official` no contêiner de inicialização para baixar os conectores. Finalmente, cada contêiner compartilhará a mesma pasta de conectores com nossos conectores oficiais já dentro. +Neste exemplo, criamos um diretório vazio como volume e o montamos nos containers. Depois rodamos `npm run cli connector add -- --official` no init container para baixar os conectores. Por fim, todo container compartilhará a mesma pasta de conectores com nossos conectores oficiais já dentro. :::note -Este é um exemplo de yaml, para executar o Logto, você precisa definir as variáveis de ambiente corretamente. +Este é um exemplo de yaml, para rodar o Logto, você precisa definir as variáveis de ambiente corretamente. ::: -Para produção, você pode substituir o volume "empty dir" por um volume persistente e fazer o trabalho de "inicialização" à sua própria maneira, você sabe o que está fazendo! +Para produção, você pode substituir o volume "empty dir" por um volume persistente, e fazer o trabalho de "init" do seu próprio jeito, você sabe o que está fazendo! -### Alteração do banco de dados \{#database-alteration} +### Alteração de banco de dados \{#database-alteration} -Semelhante aos conectores, a alteração do banco de dados precisa ser executada em uma única instância. Você pode usar um job para executar o script de alteração. +Semelhante aos conectores, a alteração do banco de dados precisa ser executada em uma única instância. Você pode usar um job para rodar o script de alteração. A variável de ambiente `CI=true` é necessária quando a alteração é executada de forma não interativa. @@ -171,4 +175,4 @@ spec: restartPolicy: Never ``` -Veja [Alteração do banco de dados](/logto-oss/using-cli/database-alteration/) para detalhes sobre o comando de alteração. +Veja [Alteração de banco de dados](/logto-oss/using-cli/database-alteration/) para detalhes sobre o comando de alteração. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..c5b1b82a1cf --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# Cofre de Segredos (Secret Vault) + +O Cofre de Segredos no Logto foi projetado para armazenar com segurança dados sensíveis do usuário — como tokens de acesso (access tokens), chaves de API (API keys), códigos de acesso (passcodes) ou qualquer outra informação confidencial que exija proteção. Esses segredos são frequentemente usados para acessar serviços de terceiros em nome do usuário, tornando o armazenamento seguro essencial. + +## Esquema de criptografia \{#encryption-scheme} + +Para proteger dados sensíveis, o Cofre de Segredos utiliza um esquema de criptografia robusto baseado em **Chaves de Criptografia de Dados (DEK)** e **Chaves de Criptografia de Chaves (KEK)**. + +- **Criptografia por segredo:** Cada segredo é criptografado com sua própria DEK exclusiva, garantindo que, mesmo que uma chave seja comprometida, os outros segredos permaneçam seguros. +- **Encapsulamento de chaves:** A própria DEK é criptografada (ou "encapsulada") com uma KEK, que é gerenciada e armazenada com segurança pelo sistema. +- **Segurança em camadas:** Essa abordagem em dois níveis garante que, mesmo que parte do sistema seja violada, os invasores não possam acessar os segredos sem tanto a DEK quanto a KEK. +- **Exposição minimizada:** Os segredos são descriptografados apenas quando absolutamente necessário, reduzindo o risco de exposição acidental e alinhando-se com as melhores práticas para o tratamento de dados sensíveis. + +Esse modelo de criptografia em camadas oferece forte proteção para as credenciais e tokens mais sensíveis dos usuários, permitindo ainda o acesso seguro quando necessário. + +## Tipos de segredos \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +Atualmente, o conjunto de tokens federados (federated token set) é o único tipo de segredo suportado nativamente. No entanto, o Cofre de Segredos foi projetado para acomodar qualquer tipo de informação sensível. Se você precisar de suporte para tipos adicionais de segredos, por favor, [entre em contato conosco](https://logto.io/contact) — teremos prazer em ajudar. +::: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..756708b38e9 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: Conjunto de tokens federados +sidebar_label: Conjunto de tokens federados +--- + +import Availability from '@components/Availability'; + + + +O conjunto de tokens federados é um tipo de segredo armazenado no Cofre de Segredos do Logto, usado para gerenciar com segurança tokens de acesso e atualização emitidos por provedores de identidade de terceiros federados. Quando um usuário se autentica via um conector social ou SSO corporativo, o Logto armazena os tokens emitidos no cofre. Esses tokens podem ser recuperados posteriormente para acessar APIs de terceiros em nome do usuário, sem exigir nova autenticação. + +## Habilitar armazenamento de tokens federados \{#enable-federated-token-storage} + +### Conectores sociais \{#social-connectors} + +:::Info +Este recurso está disponível apenas para conectores que suportam armazenamento de tokens. Os conectores atualmente suportados incluem: [GitHub](/integrations/github), [Google](/integrations/google), [Facebook](/integrations/facebook), [OAuth 2.0 padrão](/integrations/oauth2) e [OIDC padrão](/integrations/oidc). O suporte para conectores adicionais será disponibilizado gradualmente. +::: + +1. Navegue até Console > Conectores > Conectores Sociais. +2. Selecione o conector social para o qual deseja habilitar o armazenamento de tokens federados. +3. Na página "Configuração", habilite a opção **Armazenar tokens para acesso persistente à API**. + +### Conectores SSO corporativos \{#enterprise-sso-connectors} + +:::Info +O armazenamento de tokens está disponível para todos os conectores OIDC corporativos. +::: + +1. Navegue até Console > SSO Corporativo. +2. Selecione o conector SSO corporativo para o qual deseja habilitar o armazenamento de tokens federados. +3. Na guia "Experiência SSO", habilite a opção **Armazenar tokens para acesso persistente à API**. + +Certifique-se de salvar suas alterações. + +## Armazenamento de tokens \{#token-storage} + +Uma vez habilitado o armazenamento de tokens federados, o Logto armazena automaticamente os tokens de acesso e atualização emitidos pelo provedor de identidade federado sempre que um usuário se autentica por meio de um conector social ou SSO corporativo. Isso inclui: + +- [Login e cadastro social](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [Login e cadastro via SSO corporativo](/end-user-flows/enterprise-sso) +- [Vinculação de conta social via Account API](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +Os tokens armazenados são vinculados à identidade social ou SSO corporativa do usuário, permitindo que ele recupere os tokens posteriormente para acesso à API sem exigir nova autenticação. + +### Verificando o status do armazenamento de tokens \{#checking-token-storage-status} + +Você pode verificar o status do armazenamento de tokens federados de um usuário no Console do Logto: + +1. Navegue até Console > Usuários. +2. Clique no usuário que deseja inspecionar. Isso o levará à página de detalhes do usuário. +3. Role até a seção **Conexões**. Esta área lista todas as conexões sociais e SSO corporativas associadas ao usuário. +4. Cada entrada de conexão mostra um rótulo de status do token indicando se os tokens estão armazenados para essa conexão. +5. Clique na entrada da conexão para ver mais detalhes, incluindo metadados do token de acesso armazenado e disponibilidade do token de atualização (se disponível). + +Você também pode verificar as identidades de terceiros do usuário e o status do armazenamento de tokens via Management API: + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`: Recupera a identidade social de um usuário e o status do armazenamento de tokens associado à identidade por um determinado conector (por exemplo, `github`, `google`, etc.). +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`: Recupera a identidade SSO corporativa de um usuário e o status do armazenamento de tokens associado à identidade por um determinado ID de conector SSO. + +### Status do armazenamento de tokens \{#token-storage-status} + +- **Ativo**: O token de acesso está armazenado e ativo. +- **Expirado**: O token de acesso está armazenado, mas expirou. Se um token de atualização estiver disponível, ele pode ser usado para obter um novo token de acesso. +- **Inativo**: Nenhum token de acesso está armazenado para esta conexão. Isso pode ocorrer se o usuário não se autenticou por meio desta conexão ou se o armazenamento do token foi excluído. +- **Não aplicável**: O conector não suporta armazenamento de tokens. + +### Metadados do token \{#token-metadata} + +Para integridade e segurança dos dados, todos os tokens são criptografados antes de serem armazenados no Cofre de Segredos. Os valores reais dos tokens só são acessíveis ao usuário final com a devida autorização. Os desenvolvedores, por outro lado, podem apenas recuperar os metadados do conjunto de tokens para entender o estado dos tokens armazenados sem expor conteúdo sensível. + +- `createdAt`: O timestamp de quando a conexão foi estabelecida pela primeira vez e o conjunto de tokens foi inicialmente armazenado no Cofre de Segredos. +- `updatedAt`: A última vez que o conjunto de tokens foi atualizado. + - Se não houver token de atualização disponível, este valor será o mesmo que **createdAt**. + - Se houver um token de atualização, este valor reflete o momento mais recente em que o token de acesso foi atualizado. +- `hasRefreshToken`: Indica se há um token de atualização disponível. + Se o conector suportar acesso offline e a solicitação de autorização estiver devidamente configurada, o Logto armazena o token de atualização quando ele é emitido pelo provedor de identidade juntamente com o token de acesso. + Quando o token de acesso expira e existe um token de atualização válido, o Logto tenta automaticamente obter um novo token de acesso usando o token de atualização armazenado sempre que o usuário solicita acesso ao provedor conectado. +- `expiresAt`: O tempo estimado de expiração do token de acesso em **segundos**. + Isso é calculado com base no valor `expires_in` retornado pelo endpoint de token do provedor de identidade. (Este campo só está disponível se o provedor incluir `expires_in` na resposta do token.) +- `scope`: O escopo do token de acesso, indicando as permissões concedidas pelo provedor de identidade. + Isso é útil para entender quais ações podem ser realizadas com o token de acesso armazenado. (Este campo só está disponível se o provedor incluir `scope` na resposta do token.) +- `tokenType`: O tipo do token de acesso, normalmente "Bearer". + (Este campo só está disponível se o provedor incluir `token_type` na resposta do token.) + +## Recuperação de tokens \{#token-retrieval} + +Uma vez que o armazenamento de tokens está habilitado e os tokens estão armazenados com segurança no Cofre de Segredos do Logto, os usuários finais podem recuperar seus tokens de acesso de terceiros a partir do seu aplicativo cliente integrando com a [Account API](/end-user-flows/account-settings/by-account-api) do Logto. + +- `GET /my-account/identities/:target/access-token`: Recupera o token de acesso para uma identidade social especificando o conector (por exemplo, github, google). + +- `GET /my-account/sso-identities/:connectorId/access-token`: Recupera o token de acesso para uma identidade SSO corporativa especificando o ID do conector. + +:::info +Saiba como [habilitar](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) e [acessar](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) a Account API usando o token de acesso emitido pelo Logto. +::: + +### Rotação de tokens \{#token-rotation} + +Os endpoints de recuperação de tokens retornam: + +- `200` OK: Se o token de acesso for recuperado com sucesso e ainda estiver válido. +- `404` Não encontrado: Se o usuário não tiver uma identidade social ou SSO corporativa associada ao conector ou ID especificado, ou se o token de acesso não estiver armazenado. +- `401` Não autorizado: Se o token de acesso estiver expirado. + +Se o token de acesso estiver expirado e um token de atualização estiver disponível, o Logto tentará automaticamente atualizar o token de acesso e retornará o novo token de acesso na resposta. O armazenamento do token no Cofre de Segredos também será atualizado com o novo token de acesso e seus metadados. + +## Exclusão do armazenamento de tokens \{#token-storage-deletion} + +O armazenamento de tokens federados está diretamente vinculado a cada conexão social ou SSO corporativa do usuário. Isso significa que o conjunto de tokens armazenado será automaticamente excluído nos seguintes casos: + +- A identidade social ou SSO corporativa associada é removida da conta do usuário. +- A conta do usuário é excluída do seu tenant. +- O conector social ou SSO corporativo é excluído do seu tenant. + +### Revogando tokens \{#revoking-tokens} + +Você também pode excluir manualmente o conjunto de tokens de terceiros de um usuário para revogar o acesso: + +- Pelo Console: + Navegue até a página de detalhes da identidade do usuário. Role até a seção **Token de acesso** (se o armazenamento de tokens estiver disponível) e clique no botão **Excluir tokens** ao final da seção. +- Via Management API: + - `DELETE /api/secret/:id`: Exclui um segredo específico pelo seu ID, que pode ser obtido nos detalhes da identidade do usuário. + +Revogar o conjunto de tokens forçará o usuário a se autenticar novamente com o provedor de terceiros para obter um novo token de acesso antes de poder acessar as APIs de terceiros novamente. + +## Reautenticação e renovação de tokens \{#reauthentication-and-token-renewal} + +Em cenários onde um token de acesso armazenado expirou ou quando um aplicativo precisa solicitar escopos adicionais de API, os usuários finais podem se reautenticar com o provedor de terceiros para obter um novo token de acesso—sem precisar fazer login novamente no Logto. +Isso pode ser feito por meio da [Social Verification API](https://openapi.logto.io/operation/operation-createverificationbysocial) do Logto, que permite aos usuários reiniciar um fluxo de autorização social federada e atualizar seu conjunto de tokens armazenado. + +:::note +A reinicialização da autorização federada está atualmente limitada a conectores sociais. +Para conectores SSO corporativos, a reautenticação e renovação de tokens exigem que o usuário inicie novamente todo o fluxo de autenticação do Logto, pois a reautorização direta com o provedor SSO corporativo não é suportada após o login. +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as Usuário + participant Logto as Logto + participant Provider as Provedor de Terceiros + + User->>Logto: post /api/verification/social + Logto->>User: Redirecionar para provedor de terceiros + User->>Provider: Autenticar e autorizar + Provider->>User: Redirecionar de volta com código de autorização + User->>Logto: post /api/verification/social/verify com código de autorização + Logto->>User: Retornar o ID de verificação social + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. O usuário inicia uma solicitação de verificação social chamando o endpoint `POST /api/verification/social`. O usuário pode especificar escopos personalizados para solicitar permissões adicionais ao provedor de terceiros. + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**: O token de acesso do usuário emitido pelo Logto. + - **connectorId**: O ID do conector social no Logto. + - **redirectUri**: O URI para redirecionar o usuário de volta ao seu aplicativo após a autenticação. Você precisará registrar este URI nas configurações do aplicativo do provedor. + - **scope**: (Opcional) Escopos personalizados para solicitar permissões adicionais ao provedor de terceiros. Se não especificado, os escopos padrão configurados no conector serão usados. + +2. O Logto cria um novo registro de verificação social e retorna o ID de verificação social junto com a URL de autorização para redirecionar o usuário ao provedor de terceiros para autenticação. + + A resposta será semelhante a: + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. Redirecione o usuário para a URL de autorização. O usuário se autentica com o provedor de terceiros e concede permissões. + +4. O provedor de terceiros redireciona o usuário de volta ao seu aplicativo cliente com um código de autorização. + +5. Trate o callback de autorização encaminhando o código de autorização para o endpoint de verificação do Logto: + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**: O token de acesso do usuário emitido pelo Logto. + - **verificationRecordId**: O ID de verificação social retornado na etapa anterior. + - **connectorData**: O código de autorização e quaisquer outros dados retornados pelo provedor de terceiros durante o callback. + + :::note + Não se esqueça de validar o parâmetro `state` para evitar ataques CSRF. + ::: + +6. O Logto verifica o código de autorização e o troca por um novo token de acesso e token de atualização do provedor de terceiros, retornando o ID de verificação social na resposta. + +7. Por fim, atualize o armazenamento de tokens do usuário chamando o endpoint `PATCH /my-account/identities/:target/access-token` com o ID de verificação social: + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**: O token de acesso do usuário emitido pelo Logto. + - **socialVerificationId**: O ID do registro de verificação social verificado retornado na etapa anterior. + + Isso atualizará o armazenamento do conjunto de tokens do usuário no Cofre de Segredos do Logto com o novo token de acesso e token de atualização, permitindo que o usuário acesse APIs de terceiros sem precisar fazer login novamente no Logto. + + O token de acesso atualizado será retornado. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 1d3a55184b8..55d04c8f005 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -12,20 +12,32 @@ Tokens de acesso pessoal (PATs) fornecem uma maneira segura para os usuários co Você pode gerenciar tokens de acesso pessoal na página Detalhes do Usuário do Console > Gerenciamento de usuários. No cartão "Autenticação (Authentication)", você pode ver a lista de tokens de acesso pessoal e criar novos. -### Usando a Management API \{#using-management-api} +### Usando Management API \{#using-management-api} -Após configurar a [Management API](/integrate-logto/interact-with-management-api/), você pode usar os [endpoints da API](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) para criar, listar e excluir tokens de acesso pessoal. +Após configurar o [Management API](/integrate-logto/interact-with-management-api/), você pode usar os [endpoints da API](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) para criar, listar e excluir tokens de acesso pessoal. ## Usar PATs para conceder tokens de acesso (Access tokens) \{#use-pats-to-grant-access-tokens} Após criar um PAT, você pode usá-lo para conceder tokens de acesso ao seu aplicativo usando o endpoint de troca de token. +:::tip Equivalência do fluxo de token + +Tokens de acesso obtidos usando PATs funcionam **identicamente** aos tokens obtidos pelo fluxo padrão de `refresh_token`. Isso significa: + +- **Contexto de organização**: Tokens obtidos por PAT suportam as mesmas permissões e escopos de organização que os fluxos de refresh token +- **Fluxo de autorização (Authorization flow)**: Você pode usar tokens de acesso trocados por PAT para [permissões de organização](/authorization/organization-permissions) e [recursos de API em nível de organização](/authorization/organization-level-api-resources) +- **Validação de token**: A mesma lógica de validação se aplica — apenas o tipo de concessão inicial difere + +Se você estiver trabalhando com organizações, os padrões de acesso e permissões são os mesmos independentemente de usar PAT ou refresh tokens. + +::: + ### Requisição \{#request} O aplicativo faz uma [requisição de troca de token](https://auth.wiki/authorization-code-flow#token-exchange-request) para o [endpoint de token](/integrate-logto/application-data-structure#token-endpoint) do tenant com um tipo de concessão especial usando o método HTTP POST. Os seguintes parâmetros são incluídos no corpo da requisição HTTP usando o formato `application/x-www-form-urlencoded`. 1. `client_id`: OBRIGATÓRIO. O client ID do aplicativo. -2. `grant_type`: OBRIGATÓRIO. O valor deste parâmetro deve ser `urn:ietf:params:oauth:grant-type:token-exchange`, indicando que uma troca de token está sendo realizada. +2. `grant_type`: OBRIGATÓRIO. O valor deste parâmetro deve ser `urn:ietf:params:oauth:grant-type:token-exchange` indicando que uma troca de token está sendo realizada. 3. `resource`: OPCIONAL. O indicador de recurso, igual a outras requisições de token. 4. `scope`: OPCIONAL. Os escopos solicitados, igual a outras requisições de token. 5. `subject_token`: OBRIGATÓRIO. O PAT do usuário. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index af8bf496322..b21168b58aa 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -6,21 +6,23 @@ sidebar_position: 5 O Logto suporta a migração manual de usuários existentes de outra plataforma. Este guia mostrará como importar usuários existentes via Management API e falará sobre pontos que você deve considerar antes de migrar. -## Esquema de usuário \{#user-schema} +## Esquema do usuário \{#user-schema} -Antes de começarmos, vamos dar uma olhada no [esquema de usuário](/user-management/user-data/#user-profile) no Logto. Existem 3 partes do esquema de usuário que você deve conhecer: +Antes de começarmos, vamos dar uma olhada no [esquema do usuário](/user-management/user-data/#user-profile) no Logto. Existem 3 partes do esquema do usuário que você deve conhecer: -1. **Dados básicos**: são as informações básicas do perfil do usuário, você pode mapear os dados do seu perfil de usuário existente. -2. **Dados personalizados**: armazena informações adicionais do usuário, você pode usar isso para armazenar arquivos que não podem ser mapeados nos dados básicos. +1. **Dados básicos**: são as informações básicas do perfil do usuário; você pode mapear os dados do seu perfil de usuário existente. +2. **Dados personalizados**: armazena informações adicionais do usuário; você pode usar isso para armazenar arquivos que não podem ser mapeados para os dados básicos. 3. **Identidades sociais**: armazena as informações do usuário recuperadas do login social. -Você pode criar um mapa para associar as informações do seu perfil de usuário existente aos **dados básicos** e **dados personalizados**. Para login social, serão necessários passos adicionais para importar as identidades sociais; consulte a API de [Vincular identidade social ao usuário](https://openapi.logto.io/operation/operation-createuseridentity). +Você pode criar um mapa para corresponder as informações do seu perfil de usuário existente com os **dados básicos** e **dados personalizados**. Para login social, você precisará de etapas adicionais para importar as identidades sociais; consulte a API de [Vincular identidade social ao usuário](https://openapi.logto.io/operation/operation-createuseridentity). ## Hash de senha \{#password-hashing} O Logto utiliza [Argon2](https://en.wikipedia.org/wiki/Argon2) para hashear a senha do usuário, e também suporta outros algoritmos como `MD5`, `SHA1`, `SHA256` e `Bcrypt` para facilitar a migração. Esses algoritmos são considerados inseguros; os hashes de senha correspondentes serão migrados para Argon2 no primeiro login bem-sucedido do usuário. -Se você estiver usando outros algoritmos de hash ou salt, pode definir o `passwordAlgorithm` como `Legacy`, permitindo o uso de qualquer algoritmo de hash suportado pelo Node.js. Você pode encontrar a lista de algoritmos suportados na [documentação do Node.js crypto](https://nodejs.org/api/crypto.html#cryptogethashes). Nesse caso, o `passwordDigest` será uma string JSON que contém o algoritmo de hash e outros parâmetros específicos do algoritmo. +Se você estiver usando outros algoritmos de hash ou salt, pode definir o `passwordAlgorithm` como `Legacy`, o que permite usar qualquer algoritmo de hash suportado pelo Node.js. Você pode encontrar a lista de algoritmos suportados na [documentação do Node.js crypto](https://nodejs.org/api/crypto.html#cryptogethashes). Nesse caso, o `passwordDigest` será uma string JSON que contém o algoritmo de hash e outros parâmetros específicos do algoritmo. + +### Formato geral Legacy \{#general-legacy-format} O formato da string JSON é o seguinte: @@ -44,10 +46,40 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### Suporte a PBKDF2 \{#pbkdf2-support} + +O Logto suporta especificamente [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2). + +Para migrar senhas hasheadas com PBKDF2, defina o `passwordAlgorithm` como `Legacy` e formate o `passwordDigest` da seguinte forma: + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +Os parâmetros são: + +- **`salt`**: O valor do salt usado na hash original +- **`iterations`**: Número de iterações (ex: `"1000"`) +- **`keylen`**: Tamanho da chave derivada em bytes (ex: `"20"`) +- **`digest`**: A função de hash utilizada (ex: `"sha512"`, `"sha256"`, `"sha1"`) +- **`@`**: Placeholder para o valor real da senha +- **`expected_hashed_value`**: O resultado esperado do hash como uma string hexadecimal + +**Exemplo de payload de migração:** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## Etapas para migrar \{#steps-to-migrate} -1. **Prepare os dados do usuário** - Você deve primeiro exportar os dados dos usuários da sua plataforma atual e, em seguida, mapear as informações do usuário para o esquema de usuário do Logto. Recomendamos preparar os dados mapeados em formato JSON. Aqui está um exemplo dos dados do usuário: +1. **Prepare os dados dos usuários** + Primeiro, você deve exportar os dados dos usuários da sua plataforma atual e, em seguida, mapear as informações dos usuários para o esquema de usuário do Logto. Recomendamos que você prepare os dados mapeados em formato JSON. Aqui está um exemplo dos dados do usuário: ```json [ @@ -64,12 +96,12 @@ const expectedHashedValue = hash.digest('hex'); ] ``` -2. **Crie um tenant Logto** +2. **Crie um tenant no Logto** Você precisará configurar um tenant no Logto. Você pode usar tanto o Logto Cloud quanto o Logto OSS. Se ainda não fez isso, consulte o guia [Configurar Logto cloud](/introduction/set-up-logto-cloud/#create-logto-tenant). 3. **Configure a conexão com a Management API** - Usaremos a Management API para importar os dados dos usuários. Você pode consultar a [Management API](/integrate-logto/interact-with-management-api) para aprender como configurar a conexão em seu ambiente de desenvolvimento. + Usaremos a Management API para importar os dados dos usuários. Você pode consultar a [Management API](/integrate-logto/interact-with-management-api) para aprender como configurar a conexão no seu ambiente de desenvolvimento. 4. **Importe os dados dos usuários** - Recomenda-se preparar um script para importar os dados dos usuários um por um. Chamaremos a API [criar usuário](https://openapi.logto.io/operation/operation-createuser) para importar os dados. Veja um exemplo de script: + Recomenda-se preparar um script para importar os dados dos usuários um por um. Chamaremos a API [create user](https://openapi.logto.io/operation/operation-createuser) para importar os dados dos usuários. Aqui está um exemplo de script: ```jsx const users = require('./users.json'); @@ -85,10 +117,10 @@ const expectedHashedValue = hash.digest('hex'); }, body: JSON.stringify(user), }); - // Aguarde um tempo para evitar limite de taxa + // Sleep for a while to avoid rate limit await new Promise((resolve) => setTimeout(resolve, 200)); } catch (error) { - console.error(`Falha ao importar usuário ${user.username}: ${error.message}`); + console.error(`Failed to import user ${user.username}: ${error.message}`); } } }; @@ -96,7 +128,7 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -Observe que o endpoint da API possui limite de taxa; você deve adicionar uma pausa entre cada requisição para evitar o rate limit. Consulte nossa página de [limites de taxa](/integrate-logto/interact-with-management-api/#rate-limit) para mais detalhes. +Observe que o endpoint da API possui limite de taxa; você deve adicionar um tempo de espera entre cada requisição para evitar o rate limit. Consulte nossa página de [limites de taxa](/integrate-logto/interact-with-management-api/#rate-limit) para mais detalhes. Se você tiver uma grande quantidade de dados de usuários (100k+ usuários), pode [entrar em contato conosco](https://logto.io/contact) para aumentar o limite de taxa. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index b4ee1d2e4b6..17990482006 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -7,61 +7,62 @@ Logto 按以下顺序处理环境变量： - 系统环境变量 -- 项目根目录中的 `.env` 文件，符合 [dotenv](https://github.com/motdotla/dotenv#readme) 格式 +- 项目根目录下符合 [dotenv](https://github.com/motdotla/dotenv#readme) 格式的 `.env` 文件 -因此，系统环境变量将覆盖 `.env` 中的值。 +因此，系统环境变量会覆盖 `.env` 文件中的值。 ### 变量 {#variables} :::caution -如果你在项目根目录通过 `npm start` 运行日志 (Logto)，`NODE_ENV` 将始终为 `production`。 +如果你在项目根目录通过 `npm start` 运行 Logto，`NODE_ENV` 总是 `production`。 ::: -在默认值中，`protocol` 将根据你的 HTTPS 配置为 `http` 或 `https`。 - -| Key | Default Value | Type | Description | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto 运行的环境类型。 | -| PORT | `3001` | `number` | Logto 监听的本地端口。 | -| ADMIN_PORT | `3002` | `number` | Logto 管理控制台监听的本地端口。 | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 将其设置为 `1` 或 `true` 以禁用管理控制台的端口。如果未设置 `ADMIN_ENDPOINT`，它将完全禁用管理控制台。 | -| DB_URL | N/A | `string` | Logto 数据库的 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 | -| HTTPS_CERT_PATH | `undefined` | string | undefined | 详情请参见 [启用 HTTPS](#enabling-https)。 | -| HTTPS_KEY_PATH | `undefined` | string | undefined | 同上。 | -| TRUST_PROXY_HEADER | `false` | `boolean` | 同上。 | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | 你可以为在线测试或生产指定一个带有自定义域名的 URL。这也会影响 [OIDC 发行者标识符](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 你可以为生产指定一个带有自定义域名的 URL（例如 `ADMIN_ENDPOINT=https://admin.domain.com`）。这也会影响管理控制台重定向 URI 的值。 | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | 指定用户名是否区分大小写。修改此值时请谨慎；更改不会自动调整现有数据库数据，需要手动管理。 | +在默认值中，`protocol` 会根据你的 HTTPS 配置为 `http` 或 `https`。 + +| Key | 默认值 | 类型 | 描述 | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto 运行的环境类型。 | +| PORT | `3001` | `number` | Logto 监听的本地端口。 | +| ADMIN_PORT | `3002` | `number` | Logto 管理控制台监听的本地端口。 | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 设置为 `1` 或 `true` 可禁用管理控制台端口。如果未设置 `ADMIN_ENDPOINT`，将完全禁用管理控制台。 | +| DB_URL | N/A | `string` | Logto 数据库的 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 | +| HTTPS_CERT_PATH | `undefined` | string | undefined | 详情见 [启用 HTTPS](#enabling-https)。 | +| HTTPS_KEY_PATH | `undefined` | string | undefined | 同上。 | +| TRUST_PROXY_HEADER | `false` | `boolean` | 同上。 | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | 你可以为线上测试或生产环境指定自定义域名的 URL。这也会影响 [OIDC 发行者 (Issuer) 标识符](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 你可以为生产环境指定自定义域名的 URL（例如 `ADMIN_ENDPOINT=https://admin.domain.com`）。这也会影响管理控制台重定向 URI 的值。 | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | 指定用户名是否区分大小写。修改该值时请谨慎；更改不会自动调整现有数据库数据，需要手动管理。 | +| SECRET_VAULT_KEK | `undefined` | `string` | 用于加密 [Secret Vault](/secret-vault) 中数据加密密钥 (DEK) 的密钥加密密钥 (KEK)。Secret Vault 正常工作必须配置。必须为 base64 编码字符串。推荐使用 AES-256（32 字节）。示例：`crypto.randomBytes(32).toString('base64')` | ### 启用 HTTPS {#enabling-https} #### 使用 Node {#using-node} -Node 原生支持 HTTPS。提供 **BOTH** `HTTPS_CERT_PATH` 和 `HTTPS_KEY_PATH` 以通过 Node 启用 HTTPS。 +Node 原生支持 HTTPS。通过 Node 启用 HTTPS 时，需同时提供 `HTTPS_CERT_PATH` 和 `HTTPS_KEY_PATH`。 -`HTTPS_CERT_PATH` 表示你的 HTTPS 证书的路径，而 `HTTPS_KEY_PATH` 表示你的 HTTPS 密钥的路径。 +`HTTPS_CERT_PATH` 表示你的 HTTPS 证书路径，`HTTPS_KEY_PATH` 表示你的 HTTPS 密钥路径。 #### 使用 HTTPS 代理 {#using-a-https-proxy} -另一种常见做法是在 Node 前面设置一个 HTTPS 代理（例如 Nginx）。 +另一种常见做法是在 Node 前面部署一个 HTTPS 代理（如 Nginx）。 -在这种情况下，你可能希望将 `TRUST_PROXY_HEADER` 设置为 `true`，这表示是否应信任代理头字段。 Logto 将把该值传递给 [Koa 应用程序设置](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings)。 +在这种情况下，你可能需要将 `TRUST_PROXY_HEADER` 设置为 `true`，表示是否信任代理头字段。Logto 会将该值传递给 [Koa 应用设置](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings)。 -有关何时配置此字段的信息，请参见 [信任 TLS 卸载代理](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies)。 +关于何时配置该字段，请参阅 [信任 TLS 卸载代理](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies)。 ## 数据库配置 {#database-configs} -管理过多的环境变量既不高效也不灵活，因此我们的大多数通用配置都存储在数据库表 `logto_configs` 中。 +管理过多的环境变量既低效又不灵活，因此我们的大多数通用配置都存储在数据库表 `logto_configs` 中。 -该表是一个简单的键值存储，键可枚举如下： +该表是一个简单的键值存储，key 可枚举如下： -| Key | Type | Description | +| Key | 类型 | 描述 | | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------- | -| oidc.cookieKeys | string[] | [签名 cookie 密钥](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys) 的字符串数组。 | +| oidc.cookieKeys | string[] | [签名 Cookie 密钥](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys) 的字符串数组。 | | oidc.privateKeys | string[] | 用于 [OIDC JWT 签名](https://openid.net/specs/openid-connect-core-1_0.html#Signing) 的私钥内容字符串数组。 | ### 支持的私钥类型 {#supported-private-key-types} -- EC (P-256, secp256k1, P-384 和 P-521 曲线) +- EC（P-256、secp256k1、P-384 和 P-521 曲线） - RSA -- OKP (Ed25519, Ed448, X25519, X448 子类型) +- OKP（Ed25519、Ed448、X25519、X448 子类型） diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index c365936d160..5499462501f 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -17,7 +17,7 @@ Logto 的 [单点登录 (SSO) 方案](/end-user-flows/enterprise-sso) 简化了 ## 企业连接器 \{#enterprise-connectors} -Logto 为主流企业身份提供商提供了预构建的连接器，便于快速集成。如有自定义需求，我们支持通过 [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) 和 [SAML](https://auth.wiki/saml) 协议集成。 +Logto 为主流企业身份提供商提供了预构建的连接器，便于快速集成。对于自定义需求，我们支持通过 [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) 和 [SAML](https://auth.wiki/saml) 协议集成。 ### 主流企业连接器 \{#popular-enterprise-connectors} @@ -64,7 +64,7 @@ Logto 为主流企业身份提供商提供了预构建的连接器，便于快 items={[ { type: 'link', - label: 'OIDC（企业）', + label: 'OIDC (企业)', href: '/integrations/oidc-sso', customProps: { icon: , @@ -72,7 +72,7 @@ Logto 为主流企业身份提供商提供了预构建的连接器，便于快 }, { type: 'link', - label: 'SAML（企业）', + label: 'SAML (企业)', href: '/integrations/saml-sso', customProps: { icon: , @@ -85,12 +85,12 @@ Logto 为主流企业身份提供商提供了预构建的连接器，便于快 ## 配置企业连接器 \{#configuring-enterprise-connectors} -1. 进入：控制台 > 企业 SSO。 +1. 前往：控制台 > 企业 SSO。 2. 点击“添加企业连接器”按钮并选择连接器类型。 -3. 填写唯一名称（例如：Acme 公司用 Okta）。 -4. 在“连接”标签页中配置与 IdP 的连接。可参考上方各连接器类型的指南。 +3. 提供一个唯一名称（例如，Acme 公司用的 Okta）。 +4. 在“连接”标签页中配置与 IdP 的连接。每种连接器类型的配置请参考上方指南。 5. 在“体验”标签页自定义 SSO 体验和**邮箱域名**。 -6. 对于 SAML 企业连接器，可在“IdP 发起的 SSO”标签页选择性启用 IdP 发起的 SSO。[参考指南](/end-user-flows/enterprise-sso/idp-initiated-sso) 获取详情。 +6. 对于 SAML 企业连接器，可以在“IdP 发起的 SSO”标签页中选择性启用 IdP 发起的 SSO。[参考指南](/end-user-flows/enterprise-sso/idp-initiated-sso) 获取详情。 7. 保存更改。 请注意以下设置： @@ -98,38 +98,39 @@ Logto 为主流企业身份提供商提供了预构建的连接器，便于快 - **邮箱域名**：如果用户输入的邮箱的域名在某些企业 SSO 连接器的“企业邮箱域名”字段中，用户将被重定向到该 SSO 连接器对应的登录地址。 :::note - 需要注意的是，在 SSO 连接器中配置相关邮箱域名后，属于这些域名的邮箱用户登录时将被强制使用 [SSO 登录](/end-user-flows/enterprise-sso)。 + 需要注意的是，在 SSO 连接器中配置相关邮箱域名后，属于这些域名的邮箱用户将被强制使用 [SSO 登录](/end-user-flows/enterprise-sso)。 - 换句话说，只有未在 SSO 连接器中配置的域名邮箱，才可以使用“邮箱 + 验证码”或“邮箱 + 密码”登录（前提是登录体验中已启用这两种登录方式）。 + 换句话说，只有未在 SSO 连接器中配置的邮箱域名，才能使用“邮箱 + 验证码”或“邮箱 + 密码”登录（前提是登录体验中已启用这两种登录方式）。 ::: -- **同步用户资料**：选择何时同步用户资料信息（如头像、姓名）。默认行为为“仅首次登录时同步”。“每次登录时都同步”也是可选项，但可能导致自定义用户数据被覆盖。 -- **显示信息**：可选，自定义连接器的显示名称和 Logo。当多个连接器关联同一邮箱域名时非常有用。用户会在被重定向到 IdP 登录页前，从 SSO 连接器按钮列表中选择所需的 IdP。 +- **同步用户资料**：选择何时同步用户资料信息（如头像、姓名）。默认行为为“仅首次登录时同步”。“每次登录时都同步”也是一个选项，但可能导致自定义用户数据被覆盖。 +- **启用令牌存储**：对于 OIDC 企业连接器，你可以启用令牌存储功能，在用户通过企业 IdP 登录时，将访问令牌 (Access token) 和刷新令牌 (Refresh token) 安全地保存到 Logto 的 [密钥保险库](/secret-vault)。这样你的应用可以代表用户访问第三方 API，无需用户再次认证 (Authentication)。了解更多关于 [联合令牌存储](/secret-vault/federated-token-set)。 +- **显示信息**：可选，自定义连接器的显示名称和 Logo。当多个连接器关联到同一个邮箱域名时非常有用。用户会在被重定向到 IdP 登录页前，从 SSO 连接器按钮列表中选择所需的 IdP。 ## 启用企业 SSO \{#enabling-enterprise-sso} -1. 进入：控制台 > 登录体验 > 注册与登录。 +1. 前往：控制台 > 登录体验 > 注册与登录。 2. 启用“企业 SSO”开关。 3. 保存更改。 -启用后，你的登录页面会出现“单点登录 (Single Sign-On)”按钮。拥有 SSO 启用邮箱域名的企业用户可通过其企业身份提供商 (IdP) 访问你的服务。了解更多 SSO 用户体验，请参考用户流程：[企业 SSO](/end-user-flows/enterprise-sso)。 +启用后，你的登录页面会出现“单点登录 (Single Sign-On)”按钮。拥有 SSO 启用邮箱域名的企业用户可以通过其企业身份提供商 (IdP) 访问你的服务。想了解更多 SSO 用户体验，请参考用户流程：[企业 SSO](/end-user-flows/enterprise-sso)。 ## 即时加入组织 \{#just-in-time-to-organization} 在 Logto 中，[即时 (JIT) 供应](https://auth.wiki/jit-provisioning) 是一种在用户首次登录系统时，自动为其分配组织成员身份和角色的流程。 -Logto 提供了在组织内配置 SSO 连接器 JIT 供应的入口，详见[参考文档](/organizations/just-in-time-provisioning)。 +Logto 提供了在组织内配置 SSO 连接器 JIT 供应的入口，详见 [参考文档](/organizations/just-in-time-provisioning)。 ## 常见问题 \{#faqs}
-### 更改企业 SSO 连接器后对现有用户有何影响？ \{#impact-on-existing-users-after-enterprise-sso-connector-changes} +### 更改企业 SSO 连接器后对现有用户有何影响？\{#impact-on-existing-users-after-enterprise-sso-connector-changes} -- 添加 SSO：如果邮箱匹配，SSO 身份将与现有账户关联。 +- 添加 SSO：如果邮箱匹配，SSO 身份会与现有账户关联。 - 移除 SSO：会移除账户关联的 SSO 身份，但保留用户账户，并提示用户设置其他验证方式。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/social.mdx index dd7b50271d2..2704d88558f 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -7,15 +7,15 @@ sidebar_position: 3 # 社交连接器 -通过在 Logto 中启用[社交登录](/end-user-flows/sign-up-and-sign-in/social-sign-in)，简化用户注册并提高转化率。用户可以快速且安全地使用现有的社交媒体账户登录，无需创建密码或复杂的注册流程。Logto 提供多种预构建的社交连接器，并支持自定义集成以实现最大灵活性。 +通过在 Logto 启用[社交登录](/end-user-flows/sign-up-and-sign-in/social-sign-in)，简化用户注册流程并提升转化率。用户可以快速且安全地使用他们现有的社交媒体账户登录，无需创建密码或经历复杂的注册流程。Logto 提供多种预构建的社交连接器，并支持自定义集成，最大程度地满足你的灵活需求。 ## 选择你的社交连接器 \{#choose-your-social-connectors} Logto 提供两种类型的社交连接器： -### 流行的社交连接器 \{#popular-social-connectors} +### 主流社交连接器 \{#popular-social-connectors} -Logto 为流行的社交平台提供预配置的连接器，可立即使用。 +Logto 为主流社交平台提供了预配置的连接器，可直接使用。 ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'Google 连接器为你的应用程序提供了一种简洁的方式来使用 Google 的 OAuth 2.0 认证 (Authentication) 系统。', + description: 'Google 连接器为你的应用提供简洁的方式，使用 Google 的 OAuth 2.0 认证 (Authentication) 系统。', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'Facebook 连接器允许你的应用程序使用 Facebook 的 OAuth 2.0 认证 (Authentication) 系统。', + description: 'Facebook 连接器允许你的应用使用 Facebook 的 OAuth 2.0 认证 (Authentication) 系统。', customProps: { icon: , } @@ -52,7 +52,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Apple', href: '/integrations/apple', - description: 'Logto 官方的 Apple 社交登录连接器。', + description: 'Logto 官方 Apple 社交登录连接器。', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'Microsoft Azure AD 连接器为你的应用程序提供了一种简洁的方式来使用 Azure 的 OAuth 2.0 认证 (Authentication) 系统。', + description: 'Microsoft Azure AD 连接器为你的应用提供简洁的方式，使用 Azure 的 OAuth 2.0 认证 (Authentication) 系统。', customProps: { icon: , } @@ -70,7 +70,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'GitHub', href: '/integrations/github', - description: 'Logto 官方的 GitHub 社交登录连接器。', + description: 'Logto 官方 GitHub 社交登录连接器。', customProps: { icon: , } @@ -79,7 +79,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Discord', href: '/integrations/discord', - description: 'Discord 连接器为你的应用程序提供了一种使用 Discord 作为授权 (Authorization) 系统的方式。', + description: 'Discord 连接器为你的应用提供将 Discord 作为授权 (Authorization) 系统的方式。', customProps: { icon: , } @@ -88,11 +88,11 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -[更多](/integrations)... +[更多集成](/integrations)... ### 自定义你的社交连接器 \{#customize-your-social-connectors} -对于自定义需求，利用 OAuth 2.0 和 OIDC (OpenID Connect) 标准来集成你喜欢的提供商。 +如有自定义需求，可利用 OAuth 2.0 和 OIDC (OpenID Connect) 标准集成你偏好的服务商。 ```mdx-code-block , } @@ -110,7 +110,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'OIDC', href: '/integrations/oidc', - description: 'Logto 官方的 OAuth 2.0 协议连接器。', + description: 'Logto 官方 OAuth 2.0 协议连接器。', customProps: { icon: , } @@ -119,29 +119,30 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -如果我们的标准连接器无法满足你的特定需求，请随时[联系我们](https://logto.productlane.com/roadmap)。对于 OSS 用户，如果需求紧急，你可以[实现你的连接器 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector)。我们始终欢迎[贡献](/logto-oss/contribution)；你的努力可能会帮助其他有相同需求的社区成员。 +如果我们的标准连接器无法满足你的特定需求，欢迎[联系我们](https://logto.productlane.com/roadmap)。对于 OSS 用户，如果需求紧急，你可以[实现你自己的连接器 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector)。我们始终欢迎[贡献](/logto-oss/contribution)；你的努力也许能帮助有相同需求的其他社区成员。 ## 配置步骤 \{#configuration-steps} -1. 导航到 控制台 > 连接器 > 社交连接器。 -2. 点击“添加社交连接器”并选择所需类型。 -3. 按照 README 指南完成必填字段并自定义设置。 -4. 点击“保存并完成”以完成。 -5. 通过启动社交登录测试连接器。 +1. 进入 控制台 > 连接器 > 社交连接器。 +2. 点击“添加社交连接器”，选择所需类型。 +3. 按照 README 指引，填写必填项并自定义设置。 +4. 点击“保存并完成”。 +5. 通过发起社交登录测试连接器。 请注意以下设置： -- **身份提供商名称**：每个社交连接器都有一个唯一的身份提供商 (IdP) 名称以区分用户身份。常用连接器使用固定的 IdP 名称，自定义连接器需要一个唯一的值。了解更多关于 [IdP 名称](/connectors/connector-data-structure#target-identity-provider-name) 的详细信息。 -- **同步用户资料**：选择何时同步[用户资料信息](/user-management/user-data#social-identities)（例如头像、用户名）。默认设置为“仅在注册时同步”。“每次登录时同步”是一个替代选项，但可能会覆盖自定义用户数据。 +- **身份提供商名称**：每个社交连接器都有唯一的身份提供商 (IdP) 名称，用于区分用户身份。常用连接器使用固定的 IdP 名称，自定义连接器则需填写唯一值。详细了解 [IdP 名称](/connectors/connector-data-structure#target-identity-provider-name)。 +- **同步用户资料**：选择何时同步[用户资料信息](/user-management/user-data#social-identities)（如头像、用户名）。默认仅在注册时同步，也可选择“每次登录时同步”，但可能会覆盖自定义用户数据。 +- **启用令牌存储**：对于支持的社交连接器，你可以启用令牌存储功能，在用户使用社交服务商登录时，将访问令牌 (Access token) 和刷新令牌 (Refresh token) 安全地存储在 Logto 的 [Secret Vault](/secret-vault) 中。这允许你的应用在无需用户重新认证 (Authentication) 的情况下，代表用户访问第三方 API。详细了解 [联合令牌存储](/secret-vault/federated-token-set)。 ## 启用社交登录 \{#enable-social-sign-in} -一旦你成功创建了社交连接器，你可以在登录体验中将其启用为社交登录按钮（例如，继续使用 Google）。 +成功创建社交连接器后，你可以在登录体验中将其作为社交登录按钮（如“使用 Google 登录”）启用。 -1. 导航到 控制台 > 登录体验 > 注册和登录。 -2. （可选）如果只需要社交登录，可以选择“无适用”作为注册标识符。 -3. 将配置好的社交连接器添加到“社交登录”部分。 -4. 根据需要重新排序连接器。 +1. 进入 控制台 > 登录体验 > 注册和登录。 +2. （可选）如仅需社交登录，可将注册标识符选择为“不适用”。 +3. 将已配置的社交连接器添加到“社交登录”区域。 +4. 根据需要调整连接器顺序。 5. 点击“保存更改”并测试“实时预览”。 -请参考[社交登录](/end-user-flows/sign-up-and-sign-in/social-sign-in)以了解详细信息。 +参考 [社交登录](/end-user-flows/sign-up-and-sign-in/social-sign-in) 了解更多详情。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index d47e5f89d54..11ce456324a 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -12,18 +12,63 @@ import Integration from './_integration.mdx'; # 设置 Facebook 社交登录 -Logto 官方的 Facebook 社交登录连接器。 +集成 Facebook OAuth 2.0 认证 (Authentication) 系统，实现“使用 Facebook 登录”、账户绑定以及安全访问 Facebook API。 ## 开始使用 \{#get-started} -Facebook 连接器为你的应用程序提供了一种简洁的方式来使用 Facebook 的 OAuth 2.0 认证 (Authentication) 系统。 +Facebook 连接器支持 OAuth 2.0 集成，让你的应用可以： + +- 添加“使用 Facebook 登录”认证 (Authentication) +- 将用户账户与 Facebook 身份关联 +- 从 Facebook 同步用户资料信息 +- 通过 Logto Secret Vault 安全存储访问令牌 (Access token)，用于自动化任务访问 Facebook API（例如：回复帖子；在你的应用中发布内容和视频） + +要设置这些认证 (Authentication) 功能，请先在 Logto 中创建一个 Facebook 连接器： + +1. 前往 [Logto > 连接器 > 社交连接器](https://cloud.logto.io/to/connectors/social)。 +2. 点击 **添加社交连接器**，选择 **Facebook**，点击 **下一步**，并按照分步教程完成集成。 -## 参考资料 \{#references} +## 使用 Facebook 连接器 \{#utilize-the-facebook-connector} + +创建 Facebook 连接器并与 Facebook 连接后，你可以将其集成到终端用户流程中。根据你的需求选择相应的选项： + +### 启用“使用 Facebook 登录” \{#enable-sign-in-with-facebook} + +1. 在 Logto 控制台，进入 登录体验 > 注册与登录 +2. 在 **社交登录** 部分添加 Facebook 连接器，让用户可以通过 Facebook 进行认证 (Authentication) + +了解更多关于[社交登录体验](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 绑定或解绑 Facebook 账户 \{#link-or-unlink-a-facebook-account} + +使用 Account API 在你的应用中构建自定义账户中心，让已登录用户绑定或解绑他们的 Facebook 账户。[参见 Account API 教程](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以仅为账户绑定和 API 访问启用 Facebook 连接器，而无需为社交登录启用。 +::: + +### 访问 Facebook API 并执行操作 \{#access-facebook-api-and-perform-actions} + +你的应用可以从 Secret Vault 获取存储的 Facebook 访问令牌 (Access token)，调用 Facebook API 并自动化后端任务（例如发布内容或管理帖子）。请参考关于获取存储令牌用于 API 访问的指南。 + +## 管理用户的 Facebook 身份 \{#manage-user-s-facebook-identity} + +用户绑定 Facebook 账户后，管理员可以在 Logto 控制台管理该连接： + +1. 前往 用户管理 并打开该用户的资料页。 +2. 在 **社交连接** 下找到 Facebook 项，点击 **管理**。 +3. 在此页面，管理员可以管理用户的 Facebook 连接，查看所有从 Facebook 账户授权并同步的资料信息，以及检查访问令牌 (Access token) 状态。 + +:::note +Facebook 的访问令牌 (Access token) 响应不包含具体的权限 (Scope) 信息，因此 Logto 无法直接展示用户授权的权限列表。但只要用户在授权时同意了所请求的权限 (Scopes)，你的应用在访问 Facebook API 时就会拥有相应的权限。建议在 Facebook 开发者控制台和 Logto 中准确配置所需的权限 (Scopes)，以确保你的应用具备必要的访问权限。 +::: + +## 参考资料 \{#reference} + +Facebook for Developers - 文档 -- [Facebook 登录 - 文档 - Facebook for Developers](https://developers.facebook.com/docs/facebook-login/) - - [手动构建登录流程](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [权限指南](https://developers.facebook.com/docs/facebook-login/guides/permissions) +Facebook 登录文档 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index 924ee8d4226..8b9ad8ce535 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,54 +1,100 @@ -### 注册 Facebook 开发者账户 \{#register-a-facebook-developer-account} +## 第一步：在 Facebook App Dashboard 上创建应用 \{#step-1-set-up-an-app-on-facebook-app-dashboard} -如果你还没有，请[注册为 Facebook 开发者](https://developers.facebook.com/docs/development/register/) +在你可以将 Facebook 作为认证 (Authentication) 提供商之前，必须在 Facebook 开发者平台上创建一个应用，以获取 OAuth 2.0 凭据。 -### 设置 Facebook 应用 \{#set-up-a-facebook-app} +1. 如果你还没有账号，请[注册成为 Facebook 开发者](https://developers.facebook.com/docs/development/register/)。 +2. 访问 [Apps](https://developers.facebook.com/apps) 页面。 +3. 点击你已有的应用，或[创建一个新应用](https://developers.facebook.com/docs/development/create-an-app)。 -1. 访问 [Apps](https://developers.facebook.com/apps) 页面。 -2. 点击你现有的应用或[创建一个新应用](https://developers.facebook.com/docs/development/create-an-app)（如果需要）。 - - 选择的[应用类型](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types)由你决定，但它应该包含 _Facebook 登录_ 产品。 -3. 在应用仪表板页面，滚动到“添加产品”部分，并点击“Facebook 登录”卡片上的“设置”按钮。 -4. 跳过 Facebook 登录快速入门页面，点击侧边栏 -> “产品” -> “Facebook 登录” -> “设置”。 -5. 在 Facebook 登录设置页面，在“有效的 OAuth 重定向 URI”字段中填写 `${your_logto_origin}/callback/${connector_id}`。`connector_id` 可以在 Logto 管理控制台连接器详情页面的顶部栏找到。例如： - - `https://logto.dev/callback/${connector_id}` 用于生产环境 - - `https://localhost:3001/callback/${connector_id}` 用于本地环境测试 -6. 点击右下角的“保存更改”按钮。 +:::tip +用例是你的应用与 Meta 交互的主要方式，并决定了你的应用可以使用哪些 API、功能、权限和产品。如果你只需要社交认证 (Authentication)（获取 email 和 public_profile），请选择“Authentication and request data from users with Facebook Login”。如果你想访问 Facebook API，请选择你偏好的用例——大多数用例在应用创建后也支持集成“Facebook Login for business”。 +::: -## 组合连接器 JSON \{#compose-the-connector-json} +4. 应用创建后，在应用仪表盘页面，导航到 **Use cases > Facebook Login > Settings** 或 **Facebook Login for business > Settings**。 +5. 在 **Valid OAuth Redirect URIs** 中填写 Logto 的 **Callback URI**（从你的 Logto Facebook 连接器中复制）。用户通过 Facebook 登录后，会被重定向到这里，Logto 会用授权码完成认证 (Authentication)。 +6. 前往 **Use cases**，点击你的用例下的 **Customize**，添加权限 (Scopes)。建议添加 `email` 和 `public_profile`，这是在 Logto 实现 Facebook 登录所必需的。 -1. 在 Facebook 应用仪表板页面，点击侧边栏 -> “设置” -> “基本”。 -2. 你将在面板上看到“App ID”和“App secret”。 -3. 点击 App secret 输入框后的“显示”按钮以复制其内容。 -4. 填写 Logto 连接器设置： - - 在 `clientId` 字段中填写来自 _App ID_ 的字符串。 - - 在 `clientSecret` 字段中填写来自 _App secret_ 的字符串。 - - 在 `scope` 字段中填写以逗号或空格分隔的[权限](https://developers.facebook.com/docs/permissions/reference)列表字符串。如果你没有指定权限，默认权限是 `email,public_profile`。 +## 第二步：用客户端凭据配置 Logto 连接器 \{#step-2-set-up-logto-connector-with-client-credentials} -## 使用 Facebook 的测试用户测试登录 \{#test-sign-in-with-facebooks-test-users} +1. 在 Facebook App Dashboard，点击侧边栏的 **App settings > Basic**。 +2. 你会在面板上看到 **App ID** 和 **App secret**。 +3. 点击 App secret 输入框旁的 **Show** 按钮，显示并复制其内容。 +4. 配置你的 Logto Facebook 连接器设置： + - 在 `clientId` 字段填写 **App ID**。 + - 在 `clientSecret` 字段填写 **App secret**。 + - 在 Logto 中点击 **Save and Done**，将你的身份系统与 Facebook 连接。 -你可以使用测试、开发者和管理员用户的账户，在开发和实时[应用模式](https://developers.facebook.com/docs/development/build-and-test/app-modes)下测试相关应用的登录。 +## 第三步：配置权限 (Scopes) \{#step-3-configure-scopes} -你也可以直接[将应用上线](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)，以便任何 Facebook 用户都可以使用该应用登录。 +权限 (Scopes) 定义了你的应用向用户请求的权限，并控制你的项目可以从他们的 Facebook 账户访问哪些私有数据。 -- 在应用仪表板页面，点击侧边栏 -> “角色” -> “测试用户”。 -- 点击“创建测试用户”按钮以创建一个测试用户。 -- 点击现有测试用户的“选项”按钮，你将看到更多操作，例如“更改姓名和密码”。 +### 在 Facebook App Dashboard 配置权限 (Scopes) \{#configure-scopes-in-facebook-app-dashboard} -## 发布 Facebook 登录设置 \{#publish-facebook-sign-in-settings} +1. 前往 **Facebook App Dashboard > Use cases**，点击 **Customize** 按钮。 +2. 只添加你的应用所需的权限 (Scopes)。用户会在 Facebook 用户授权页面 (Consent screen) 上审核并授权这些权限： + - **用于认证 (Authentication)（必需）**：`email` 和 `public_profile`。 + - **用于 API 访问（可选）**：你的应用需要的其他权限 (Scopes)（如访问 Threads API 的 `threads_content_publish`、`threads_read_replies`）。可浏览 [Meta Developer Documentation](https://developers.facebook.com/docs/) 获取可用服务。 -通常，只有测试、管理员和开发者用户可以在[开发模式](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode)下使用相关应用登录。 +### 在 Logto 中配置权限 (Scopes) \{#configure-scopes-in-logto} -为了让普通 Facebook 用户在生产环境中使用该应用登录，你可能需要将你的 Facebook 应用切换到*[实时模式](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)*，这取决于应用类型。例如，纯*商业类型*应用没有“实时”切换按钮，但这不会阻碍你的使用。 +根据你的需求选择以下一种或多种方式： -1. 在 Facebook 应用仪表板页面，点击侧边栏 -> “设置” -> “基本”。 -2. 如果需要，在面板上填写“隐私政策 URL”和“用户数据删除”字段。 -3. 点击右下角的“保存更改”按钮。 -4. 点击应用顶部栏的“实时”切换按钮。 +**方式一：不需要额外 API 权限 (Scopes)** -## 配置类型 \{#config-types} +- 在 Logto Facebook 连接器的 `Scopes` 字段留空。 +- 默认会请求 `email public_profile` 权限 (Scopes)，以确保 Logto 能正确获取基础用户信息。 -| 名称 | 类型 | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**方式二：登录时请求额外权限 (Scopes)** + +- 在 **Scopes** 字段输入所有需要的权限 (Scopes)，用空格分隔。 +- 你在这里填写的权限 (Scopes) 会覆盖默认值，所以请务必包含认证 (Authentication) 权限：`email public_profile`。 + +**方式三：后续按需增量请求权限 (Scopes)** + +- 用户登录后，你可以通过重新发起联合社交授权 (Authorization) 流程并更新用户存储的令牌集，按需请求更多权限 (Scopes)。 +- 这些额外权限 (Scopes) 无需在 Logto Facebook 连接器的 `Scopes` 字段填写，可通过 Logto 的 Social Verification API 实现。 + +按照这些步骤操作后，你的 Logto Facebook 连接器只会请求你的应用所需的权限 (Scopes)，不多也不少。 + +:::tip +如果你的应用请求这些权限 (Scopes) 以访问 Facebook API 并执行操作，请确保在 Logto Facebook 连接器中启用 **Store tokens for persistent API access**。详情见下一节。 +::: + +## 第四步：通用设置 \{#step-4-general-settings} + +以下是一些不会阻止 Facebook 连接但可能影响终端用户认证 (Authentication) 体验的通用设置。 + +### 同步用户资料信息 \{#sync-profile-information} + +在 Facebook 连接器中，你可以设置同步用户资料（如用户名和头像）的策略。可选项包括： + +- **仅在注册时同步**：用户首次登录时获取一次资料信息。 +- **每次登录时都同步**：用户每次登录时都会更新资料信息。 + +### 存储令牌以访问 Facebook API（可选） \{#store-tokens-to-access-facebook-apis-optional} + +如果你希望访问 Facebook API 并在用户授权下执行操作（无论是社交登录还是账号绑定），Logto 需要获取特定 API 权限 (Scopes) 并存储令牌。 + +1. 按照上方教程添加所需权限 (Scopes)。 +2. 在 Logto Facebook 连接器中启用 **Store tokens for persistent API access**。Logto 会将 Facebook 访问令牌安全地存储在 Secret Vault 中。 + +:::note +Facebook 不提供刷新令牌 (Refresh tokens)。但当启用令牌存储后，Logto 会在用户认证 (Authentication) 时自动请求一个长期有效的访问令牌（60 天）。在此期间，用户可以手动撤销访问令牌，否则无需重新授权即可访问 Facebook API。注意：不要在 `Scope` 字段添加 `offline_access`，否则可能导致错误。 +::: + +## 第五步：用 Facebook 测试用户测试登录（可选） \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +你可以使用测试、开发者和管理员账号测试应用登录。你也可以直接发布应用，让任何 Facebook 用户都能登录。 + +1. 在 Facebook App Dashboard，点击侧边栏 **App roles > Test Users**。 +2. 点击 **Create test users** 按钮创建测试用户。 +3. 点击已有测试用户的 **Options** 按钮查看更多操作，如“更改姓名和密码”。 + +## 第六步：发布 Facebook 登录设置 \{#step-6-publish-facebook-sign-in-settings} + +通常，只有测试、管理员和开发者用户可以登录应用。要让普通 Facebook 用户在生产环境中登录应用，你可能需要发布该应用。 + +1. 在 Facebook App Dashboard，点击侧边栏 **Publish**。 +2. 如有需要，填写 **Privacy Policy URL** 和 **User data deletion** 字段。 +3. 点击右下角的 **Save changes** 按钮。 +4. 点击应用顶部栏的 **Live** 开关按钮。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index 98ad3b583a2..d31abb27e90 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -3,8 +3,8 @@ slug: /integrations/github sidebar_label: GitHub sidebar_custom_props: darkLogoFilename: 'github-dark.svg' - description: GitHub 是一个用于软件开发和版本控制的在线社区。 -tutorial_config_name: GitHub OAuth 应用 + description: GitHub 是一个面向软件开发和版本控制的在线社区。 +tutorial_config_name: GitHub OAuth app --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -13,26 +13,71 @@ import Integration from './_integration.mdx'; # 设置 GitHub 社交登录 -Logto 官方的 GitHub 社交登录连接器。 +集成 GitHub OAuth app 以启用“使用 GitHub 登录”、账户绑定，以及安全访问 GitHub API。 ## 开始使用 \{#get-started} -GitHub 连接器使终端用户能够通过 GitHub OAuth 2.0 认证 (Authentication) 协议使用他们自己的 GitHub 账户登录到你的应用程序。 +GitHub 连接器支持 OAuth 2.0 集成，让你的应用可以： + +- 添加“使用 GitHub 登录”认证 (Authentication) +- 将用户账户与 GitHub 身份绑定 +- 从 GitHub 同步用户资料信息 +- 通过 Logto Secret Vault 安全存储令牌访问 GitHub API，实现自动化任务（例如，从你的应用创建 GitHub 问题、管理仓库） + +要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 GitHub 连接器： + +1. 前往 Logto 控制台 > 连接器 > 社交连接器。 +2. 点击 **添加社交连接器**，选择 **GitHub**，点击 **下一步**，并按照分步教程完成集成。 -## 测试 GitHub 连接器 \{#test-github-connector} +## 使用 GitHub 连接器 \{#utilize-the-github-connector} + +创建好 GitHub 连接器并与 GitHub 连接后，你可以将其集成到终端用户流程中。根据你的需求选择相应选项： + +### 启用“使用 GitHub 登录” \{#enable-sign-in-with-github} + +1. 在 Logto 控制台，前往 登录体验 > 注册与登录。 +2. 在 **社交登录** 部分添加 GitHub 连接器，让用户可以通过 GitHub 认证 (Authentication)。 + +了解更多关于[社交登录体验](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 绑定或解绑 GitHub 账户 \{#link-or-unlink-a-github-account} + +使用 Account API 在你的应用中构建自定义账户中心，让已登录用户绑定或解绑他们的 GitHub 账户。[参见 Account API 教程](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -就是这样。GitHub 连接器现在应该可用了。别忘了[在登录体验中启用社交连接器](/connectors/social-connectors/#enable-social-sign-in)。 +:::tip +你可以只为账户绑定和 API 访问启用 GitHub 连接器，而不启用社交登录。 +::: -## 参考 \{#reference} +### 访问 GitHub API 并执行操作 \{#access-github-apis-and-perform-actions} + +你的应用可以从 Secret Vault 获取存储的 GitHub 访问令牌 (Access token)，调用 GitHub API 并自动化后端任务（例如，创建问题、管理仓库或自动化工作流）。请参考关于检索存储令牌以访问 API 的指南。 + +## 管理用户的 GitHub 身份 \{#manage-user-s-github-identity} + +用户绑定 GitHub 账户后，管理员可以在 Logto 控制台管理该连接： + +1. 前往 Logto 控制台 > 用户管理 并打开该用户的资料页。 +2. 在 **社交连接** 下找到 GitHub 项，点击 **管理**。 +3. 在此页面，管理员可以管理用户的 GitHub 连接，查看所有从其 GitHub 账户授权并同步的资料信息，并检查访问令牌 (Access token) 状态。 + +:::note +GitHub 的访问令牌 (Access token) 响应不包含具体的权限 (Scope) 信息，因此 Logto 无法直接显示用户授权的权限 (Permissions) 列表。但只要用户在授权时同意了所请求的权限 (Scopes)，你的应用在访问 GitHub API 时就会拥有相应的权限 (Permissions)。 +::: + +## 参考资料 \{#reference} - GitHub - 开发者 - 应用 + GitHub 开发者文档 - 关于应用 - GitHub - 开发者 - 应用 - 创建 OAuth 应用 + GitHub 开发者文档 - 创建 OAuth 应用 + + + + GitHub OAuth 应用权限 (Scopes) 文档 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index 4ad294f2b2b..aa3b793efc4 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,36 +1,99 @@ -### 使用 GitHub 账户登录 \{#sign-in-with-github-account} +## 第一步：在 GitHub 上创建 OAuth 应用 \{#step-1-create-an-oauth-app-on-github} -访问 [GitHub 网站](https://github.com/)并使用你的 GitHub 账户登录。如果你没有账户，可以注册一个新账户。 +在你可以将 GitHub 用作认证 (Authentication) 提供商之前，必须在 GitHub 上创建一个 OAuth 应用以获取 OAuth 2.0 凭据。 -### 创建和配置 OAuth 应用 \{#create-and-configure-oauth-app} +1. 前往 [GitHub](https://github.com/) 并使用你的账户登录，或根据需要创建新账户。 +2. 导航到 [Settings > Developer settings > OAuth apps](https://github.com/settings/developers)。 +3. 点击 **New OAuth App** 注册新应用： + - **Application name**：输入你的应用的描述性名称。 + - **Homepage URL**：输入你的应用主页 URL。 + - **Authorization callback URL**：从 Logto GitHub 连接器复制 **Callback URI** 并粘贴到此处。用户通过 GitHub 登录后，将被重定向到这里，并携带 Logto 用于完成认证 (Authentication) 的授权码。 + - **Application description**：（可选）添加你的应用的简要描述。 +4. 点击 **Register application** 创建 OAuth 应用。 -按照[创建 OAuth 应用](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)指南，注册一个新应用。 +:::note +建议不要勾选 **Enable Device Flow**，因为通过移动设备使用 GitHub 登录的用户需要在 GitHub 移动应用中确认首次登录操作。许多 GitHub 用户并未在手机上安装 GitHub 移动应用，这可能会阻断登录流程。只有在你预期终端用户会通过 GitHub 移动应用确认登录流程时才启用此项。详见 [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)。 -在 **Application name** 中为你的新 OAuth 应用命名，并填写应用的 **Homepage URL**。你可以将 **Application description** 字段留空，并将 **Authorization callback URL** 自定义为 `${your_logto_origin}/callback/${connector_id}`。`connector_id` 可以在 Logto 管理控制台连接器详情页面的顶部栏找到。 +关于设置 GitHub OAuth 应用的更多细节，请参阅 [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)。 +::: -:::note +## 第二步：配置你的 Logto 连接器 \{#step-2-configure-your-logto-connector} + +在 GitHub 中创建 OAuth 应用后，你会被重定向到详情页面，在那里可以复制 Client ID 并生成 Client secret。 + +1. 从你的 GitHub OAuth 应用复制 **Client ID**，并粘贴到 Logto 的 `clientId` 字段中。 +2. 在 GitHub 中点击 **Generate a new client secret** 创建新密钥，然后复制并粘贴到 Logto 的 `clientSecret` 字段中。 +3. 在 Logto 中点击 **Save and Done**，将你的身份系统与 GitHub 连接。 + +:::warning +请妥善保管你的 Client secret，切勿在客户端代码中暴露。GitHub 的 client secret 丢失后无法找回——你需要重新生成一个新的。 +::: + +## 第三步：配置权限范围（可选） \{#step-3-configure-scopes-optional} + +权限范围（Scopes）定义了你的应用从用户处请求的权限，并控制你的应用可以访问其 GitHub 账户的哪些数据。 + +在 Logto 的 `Scopes` 字段中，可以向 GitHub 请求额外权限。根据你的需求选择以下方式之一： + +### 方案一：无需额外 API 权限范围 \{#option-1-no-extra-api-scopes-needed} + +- 保持 Logto GitHub 连接器中的 `Scopes` 字段为空。 +- 默认会请求 `read:user` 权限范围，以确保 Logto 能正确获取基本用户信息（如邮箱、姓名、头像）。 -如果在登录时遇到错误信息“重定向 URI 必须与此应用程序注册的回调 URL 匹配。”，请尝试对齐 GitHub OAuth 应用的授权回调 URL 和 Logto 应用的重定向 URL（当然，包括协议）以解决问题。 +### 方案二：登录时请求额外权限范围 \{#option-2-request-additional-scopes-at-sign-in} +- 浏览所有可用的 [GitHub OAuth 应用权限范围](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)，仅添加你的应用所需的权限范围。 +- 在 **Scopes** 字段中输入所有需要的权限范围，使用空格分隔。 +- 你在此处填写的权限范围会覆盖默认值，因此请务必包含认证 (Authentication) 权限范围：`read:user`。 +- 常见的额外权限范围包括： + - `repo`：完全控制私有仓库 + - `public_repo`：访问公共仓库 + - `user:email`：访问用户邮箱地址 + - `notifications`：访问通知 +- 请确保所有权限范围拼写正确且有效。拼写错误或不支持的权限范围会导致 GitHub 返回 “Invalid scope” 错误。 + +### 方案三：后续按需请求增量权限范围 \{#option-3-request-incremental-scopes-later} + +- 用户登录后，你可以通过重新发起联合社交授权流程并更新用户存储的令牌集，按需请求额外权限范围。 +- 这些额外权限范围无需在 Logto GitHub 连接器的 `Scopes` 字段中填写，可以通过 Logto 的 Social Verification API 实现。 + +按照上述步骤操作后，你的 Logto GitHub 连接器只会请求你的应用所需的权限——不多也不少。 + +:::tip +如果你的应用请求这些权限范围以访问 GitHub API 并执行操作，请确保在 Logto GitHub 连接器中启用 **Store tokens for persistent API access**。详见下一节。 ::: -我们建议不要勾选 **Enable Device Flow** 前的框，否则在移动设备上使用 GitHub 登录的用户必须在 GitHub 应用中确认初始登录操作。许多 GitHub 用户没有在手机上安装 GitHub 移动应用，这可能会阻碍登录流程。如果你希望终端用户确认他们的登录流程，请忽略我们的建议。查看 [设备流](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow) 的详细信息。 +## 第四步：常规设置 \{#step-4-general-settings} + +以下是一些不会阻止与 GitHub 连接但可能影响终端用户认证 (Authentication) 体验的常规设置。 + +### 同步资料信息 \{#sync-profile-information} -### 管理 OAuth 应用 \{#managing-oauth-apps} +在 GitHub 连接器中，你可以设置同步资料信息（如用户名和头像）的策略。可选项包括： -访问 [OAuth 应用页面](https://github.com/settings/developers)，你可以添加、编辑或删除现有的 OAuth 应用。 -你还可以在 OAuth 应用详情页面找到 `Client ID` 并生成 `Client secrets`。 +- **仅在注册时同步**：用户首次登录时获取一次资料信息。 +- **每次登录时都同步**：每次用户登录时都会更新资料信息。 -### 配置你的连接器 \{#configure-your-connector} +### 存储令牌以访问 GitHub API（可选） \{#store-tokens-to-access-github-apis-optional} + +如果你希望在获得用户授权后访问 GitHub API 并执行操作（无论是通过社交登录还是账户绑定），Logto 需要获取特定 API 权限范围并存储令牌。 + +1. 按上述说明添加所需权限范围。 +2. 在 Logto GitHub 连接器中启用 **Store tokens for persistent API access**。Logto 会将 GitHub 访问令牌安全地存储在 Secret Vault 中。 + +:::note +当你按照本教程使用 GitHub **OAuth App** 时，无法从 GitHub 获取刷新令牌 (Refresh token)，因为其访问令牌 (Access token) 不会过期，除非用户手动撤销。因此，无需在 `Scopes` 字段中添加 `offline_access`，否则可能导致错误。 + +如果你希望访问令牌 (Access token) 过期或使用刷新令牌 (Refresh token)，建议集成 **GitHub App**。了解 [GitHub App 与 OAuth App 的区别](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)。 +::: -在 `clientId` 和 `clientSecret` 字段中填写你从上一节提到的 OAuth 应用详情页面获得的 _Client ID_ 和 _Client Secret_。 +## 第五步：测试你的集成（可选） \{#step-5-test-your-integration-optional} -`scope` 是一个以空格分隔的[权限 (Scopes)](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)列表。如果未提供，权限 (Scope) 默认为 `read:user`。 +在正式上线前，测试你的 GitHub 集成： -### 配置类型 \{#config-types} +1. 在 Logto 开发租户中使用该连接器。 +2. 验证用户是否可以通过 GitHub 登录。 +3. 检查是否请求了正确的权限范围。 +4. 如果你存储了令牌，测试 API 调用。 -| 名称 | 类型 | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +GitHub OAuth 应用可立即与任何 GitHub 用户账户配合使用——无需像其他平台那样设置测试用户或应用审核。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index 42aef0a2fdb..0b56f6d98b6 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -12,14 +12,66 @@ import Integration from './_integration.mdx'; # 设置 Google 社交登录 -Google 连接器为你的应用程序提供了一种简洁的方式来使用 Google 的 OAuth 2.0 认证 (Authentication) 系统。 +集成 Google OAuth 2.0 认证 (Authentication) 系统，实现 Google 登录、账户关联以及安全访问 Google API。 +## 开始使用 \{#get-started} + +Google 连接器 (Connector) 支持 OAuth 2.0 集成，让你的应用可以： + +- 添加“使用 Google 登录”认证 (Authentication) +- 将用户账户与 Google 身份关联 +- 从 Google 同步用户资料信息 +- 通过 Logto Secret Vault 安全存储令牌访问 Google API，实现自动化任务（如编辑 Google Docs、管理应用内的日历事件） + +要设置这些认证 (Authentication) 功能，首先需要在 Logto 创建一个 Google 连接器 (Connector)： + +1. 前往 Logto 控制台 > 连接器 (Connector) > 社交连接器 (Connector)。 +2. 点击 **添加社交连接器 (Connector)**，选择 **Google**，点击 **下一步**，并按照分步教程完成集成。 + -## 参考资料 \{#references} +## 使用 Google 连接器 (Connector) \{#utilize-the-google-connector} + +创建好 Google 连接器 (Connector) 并与 Google 连接后，你可以将其集成到终端用户流程中。根据你的需求选择合适的选项： + +### 启用“使用 Google 登录” \{#enable-sign-in-with-google} + +1. 在 Logto 控制台，前往 登录体验 > 注册与登录。 +2. 在 **社交登录** 部分添加 Google 连接器 (Connector)，让用户可以通过 Google 认证 (Authentication)。 +3. 可选：在登录和注册页面启用 **Google One Tap**，为用户提供更流畅的认证 (Authentication) 体验。 + +了解更多关于[社交登录体验](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 关联或解除关联 Google 账户 \{#link-or-unlink-a-google-account} + +使用 Account API 在你的应用中构建自定义账户中心，让已登录用户可以关联或解除关联他们的 Google 账户。[参见 Account API 教程](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以只为账户关联和 API 访问启用 Google 连接器 (Connector)，而不启用社交登录。 +::: + +### 访问 Google API 并执行操作 \{#access-google-apis-and-perform-actions} + +你的应用可以从 Secret Vault 获取已存储的 Google 访问令牌 (Access token)，调用 Google API 并自动化后端任务（例如管理 Google Drive 文件、创建日历事件或通过 Gmail 发送邮件）。参考相关指南获取用于 API 访问的存储令牌。 + +## 管理用户的 Google 身份 \{#manage-user-s-google-identity} + +用户关联 Google 账户后，管理员可以在 Logto 控制台管理该连接： + +1. 前往 Logto 控制台 > 用户管理 并打开该用户的资料页。 +2. 在 **社交连接** 部分找到 Google 项，点击 **管理**。 +3. 在此页面，管理员可以管理用户的 Google 连接，查看所有从 Google 账户授权并同步的资料信息，以及检查访问令牌 (Access token) 状态。 + +## 参考资料 \{#reference} Google 身份：设置 OAuth 2.0 + + + Google 身份服务（One Tap） + + +Google Cloud 控制台 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index b50561793fd..c0229fa197d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## 在 Google API Console 中设置项目 \{#set-up-a-project-in-the-google-api-console} +## 步骤 1：在 Google Auth Platform 创建项目 \{#step-1-create-a-project-on-google-auth-platform} + +在你使用 Google 作为认证 (Authentication) 提供商之前，必须在 Google Cloud Console 中设置一个项目以获取 OAuth 2.0 凭据。如果你已经有项目，可以跳过此步骤。 + +1. 访问 [Google Cloud Console](https://console.cloud.google.com/) 并使用你的 Google 账号登录。 +2. 点击顶部菜单栏的 **选择项目** 按钮，然后点击 **新建项目** 按钮来创建一个项目。 +3. 在你新创建的项目中，导航到 **API 和服务 > OAuth 用户授权页面** 配置你的应用： + - **应用信息**：输入将在授权页面显示的 **应用名称** 和 **支持邮箱** + - **受众 (Audience)**：选择你偏好的受众类型： + - **内部** - 仅适用于你组织内的 Google Workspace 用户 + - **外部** - 适用于任何 Google 用户（生产环境需验证） + - **联系信息**：提供邮箱地址，以便 Google 在项目有变更时通知你 + - 勾选 **我同意 Google 的政策** 完成基础设置 +4. 可选，前往 **品牌** 部分编辑产品信息并上传你的 **应用 Logo**，该 Logo 会显示在 OAuth 用户授权页面，帮助用户识别你的应用。 + +:::tip +如果你选择了 **外部** 受众类型，开发期间需要添加测试用户，并在生产环境发布你的应用。 +::: + +## 步骤 2：创建 OAuth 2.0 凭据 \{#step-2-create-oauth-2-0-credentials} + +在 Google Cloud Console 的 [凭据](https://console.cloud.google.com/apis/credentials) 页面为你的应用创建 OAuth 凭据。 + +1. 点击 **创建凭据 > OAuth 客户端 ID**。 +2. 选择 **Web 应用程序** 作为应用类型。 +3. 填写你的 OAuth 客户端的 **名称**。这有助于你识别凭据，不会显示给终端用户。 +4. 配置授权的 URI： + - **授权的 JavaScript 来源**：添加你的 Logto 实例的来源（如 `https://your-logto-domain.com`） + - **授权的重定向 URI**：添加 Logto 的 **回调 URI**（可从你的 Logto Google 连接器中复制） +5. 点击 **创建** 生成 OAuth 客户端。 + +## 步骤 3：用凭据配置 Logto 连接器 \{#step-3-configure-logto-connector-with-credentials} + +创建 OAuth 客户端后，Google 会弹出一个包含你凭据的窗口： + +1. 复制 **Client ID** 并粘贴到 Logto 的 `clientId` 字段 +2. 复制 **Client secret** 并粘贴到 Logto 的 `clientSecret` 字段 +3. 在 Logto 中点击 **保存并完成**，将你的身份系统与 Google 连接 + +:::warning +请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即生成新的 secret。 +::: + +## 步骤 4：配置权限 (Scopes) \{#step-4-configure-scopes} + +权限 (Scopes) 定义了你的应用向用户请求的权限，并控制你的应用可以访问他们 Google 账号中的哪些数据。 + +### 在 Google Cloud Console 配置权限 (Scopes) \{#configure-scopes-in-google-cloud-console} + +1. 导航到 **API 和服务 > OAuth 用户授权页面 > 权限 (Scopes)**。 +2. 点击 **添加或移除权限**，只选择你的应用所需的权限： + - **认证 (Authentication)（必需）**： + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **API 访问（可选）**：根据你的应用需求添加其他权限（如 Drive、Calendar、YouTube）。浏览 [Google API Library](https://console.cloud.google.com/apis/library) 查找可用服务。如果你的应用需要访问除基础权限外的 Google API，请先在 Google API Library 启用相应 API（如 Google Drive API、Gmail API、Calendar API）。 +3. 点击 **更新** 确认选择。 +4. 点击 **保存并继续** 应用更改。 -- 访问 [Google API Console](https://console.developers.google.com) 并使用你的 Google 账户登录。 -- 点击顶部菜单栏的 **Select a project** 按钮，然后点击 **New Project** 按钮创建一个项目。 -- 在你新创建的项目中，点击 **APIs & Services** 进入 **APIs & Services** 菜单。 +### 在 Logto 中配置权限 (Scopes) \{#configure-scopes-in-logto} -## 配置你的用户授权页面 \{#configure-your-consent-screen} +根据你的需求选择以下一种或多种方式： -### 配置并注册你的应用程序 \{#configure-and-register-your-application} +**方式 1：无需额外 API 权限** -- 在左侧 **APIs & Services** 菜单中，点击 **OAuth consent screen** 按钮。 -- 选择你想要的 **User Type**，然后点击 **Create** 按钮。（注意：如果你选择 **External** 作为你的 **User Type**，你需要稍后添加测试用户。） +- 在 Logto Google 连接器的 `Scopes` 字段留空。 +- 默认会请求 `openid profile email` 权限，确保 Logto 能正确获取基础用户信息。 -现在你将进入 **Edit app registration** 页面。 +**方式 2：登录时请求额外权限** -### 编辑应用程序注册 \{#edit-app-registration} +- 在 **Scopes** 字段输入所有需要的权限，使用空格分隔。 +- 你填写的权限会覆盖默认值，因此务必包含认证 (Authentication) 权限：`https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`。 +- 使用完整的权限 URL。例如：`https://www.googleapis.com/auth/calendar.readonly`。 -#### 配置 OAuth 用户授权页面 \{#config-oauth-consent-screen} +**方式 3：后续按需增量请求权限** -- 按照说明填写 **OAuth consent screen** 表单。 -- 点击 **SAVE AND CONTINUE** 继续。 +- 用户登录后，可以通过重新发起联合社交授权 (Authorization) 流程并更新用户存储的令牌集，按需请求额外权限。 +- 这些额外权限无需预先填写在 Logto Google 连接器的 `Scopes` 字段，可通过 Logto 的 Social Verification API 实现。 -#### 配置权限 (Scopes) \{#config-scopes} +按照这些步骤操作后，你的 Logto Google 连接器只会请求你的应用所需的权限——不多也不少。 -- 点击 **ADD OR REMOVE SCOPES**，在弹出的抽屉中选择 `../auth/userinfo.email`、`../auth/userinfo.profile` 和 `openid`，然后点击 **UPDATE** 完成。建议你考虑添加所有可能使用的权限 (Scopes)，否则你在配置中添加的一些权限可能无法正常工作。 -- 根据需要填写表单。 -- 点击 **SAVE AND CONTINUE** 继续。 +:::tip +如果你的应用请求这些权限以访问 Google API 并执行操作，请确保在 Logto Google 连接器中启用 **为持久 API 访问存储令牌**。详见下一节。 +::: -#### 添加测试用户（仅限外部用户类型）\{#add-test-users-external-user-type-only} +## 步骤 5：自定义认证 (Authentication) 提示 \{#step-5-customize-authentication-prompts} -- 点击 **ADD USERS** 并添加测试用户，以允许这些用户在测试时访问你的应用程序。 -- 点击 **SAVE AND CONTINUE** 继续。 +在 Logto 中配置 **Prompts**，以控制用户认证 (Authentication) 体验。Prompts 是一个字符串数组，指定所需的用户交互类型： -现在你应该已经配置好了 Google OAuth 2.0 用户授权页面。 +- `none` - 授权服务器不会显示任何认证 (Authentication) 或授权 (Consent) 页面。如果用户尚未认证 (Authentication) 且未预先授权所请求的权限，将返回错误。用于检查现有认证 (Authentication) 和/或授权 (Consent)。 +- `consent` - 授权服务器在向客户端返回信息前提示用户授权 (Consent)。启用 Google API 离线访问（offline access）时必需。 +- `select_account` - 授权服务器提示用户选择一个账号。适用于拥有多个 Google 账号的用户选择用于认证 (Authentication) 的账号。 -## 获取 OAuth 2.0 凭证 \{#obtain-oauth-20-credentials} +## 步骤 6：通用设置 \{#step-6-general-settings} -- 在左侧 **APIs & Services** 菜单中，点击 **Credentials** 按钮。 -- 在 **Credentials** 页面，点击顶部菜单栏的 **+ CREATE CREDENTIALS** 按钮，并选择 **OAuth client ID**。 -- 在 **Create OAuth client ID** 页面，选择 **Web application** 作为应用程序类型。 -- 填写你的应用程序的基本信息。 -- 点击 **+ Add URI**，在 **Authorized JavaScript origins** 部分添加一个授权域名。这是你的 Logto 授权页面将从中提供服务的域名。在我们的例子中，这将是 `${your_logto_origin}`。例如 `https://logto.dev`。 -- 在 **Authorized redirect URIs** 部分点击 **+ Add URI**，设置 **Authorized redirect URIs**，它将在用户登录后将其重定向到应用程序。在我们的例子中，这将是 `${your_logto_endpoint}/callback/${connector_id}`。例如 `https://logto.dev/callback/${connector_id}`。`connector_id` 可以在 Logto 管理控制台连接器详情页面的顶部栏找到。 -- 点击 **Create** 完成，然后你将获得 **Client ID** 和 **Client Secret**。 +以下是一些不会阻止与 Google 连接但可能影响终端用户认证 (Authentication) 体验的通用设置。 -## 配置你的连接器 \{#configure-your-connector} +### 同步资料信息 \{#sync-profile-information} -使用前一节中提到的 OAuth 应用程序详细信息页面中获得的 _Client ID_ 和 _Client Secret_ 填写 `clientId` 和 `clientSecret` 字段。 +在 Google 连接器中，你可以设置同步资料信息（如用户名和头像）的策略。可选项包括： -`scope` 是一个以空格分隔的 [scopes](https://developers.google.com/identity/protocols/oauth2/scopes) 列表。如果未提供，scope 默认为 `openid profile email`。 +- **仅在注册时同步**：用户首次登录时获取一次资料信息。 +- **每次登录时同步**：每次用户登录时都会更新资料信息。 -`prompts` 是一个字符串数组，指定所需的用户交互类型。字符串可以是以下值之一： +### 存储令牌以访问 Google API（可选） \{#store-tokens-to-access-google-apis-optional} -- `none`：授权服务器不显示任何认证 (Authentication) 或用户授权页面；如果用户尚未认证 (Authentication) 并且未预先配置请求权限的同意，将返回错误。你可以使用 none 检查现有的认证 (Authentication) 和/或同意。 -- `consent`：授权服务器在向客户端返回信息之前提示用户同意。 -- `select_account`：授权服务器提示用户选择一个用户账户。这允许拥有多个账户的用户在授权服务器上选择他们可能有当前会话的多个账户之一。 +如果你希望访问 [Google API](https://console.cloud.google.com/apis/library) 并在用户授权下执行操作（无论是社交登录还是账号绑定），Logto 需要获取特定 API 权限并存储令牌。 -### 配置类型 \{#config-types} +1. 在 Google Cloud Console 的 OAuth 用户授权页面配置和 Logto Google 连接器中添加所需权限。 +2. 在 Logto Google 连接器中启用 **为持久 API 访问存储令牌**。Logto 会将 Google 访问令牌和刷新令牌安全地存储在 Secret Vault 中。 +3. 为确保返回刷新令牌，请按如下方式配置 Logto Google 连接器： + - 在 **Prompts** 中包含 `consent` + - 启用 **离线访问** -| 名称 | 类型 | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +你无需在 Logto 的 `Scope` 字段中添加 `offline_access` —— 添加可能导致错误。Google 在启用离线访问时会自动使用 `access_type=offline`。 +::: -## 启用 Google One Tap \{#enable-google-one-tap} +## 步骤 7：启用 Google One Tap（可选） \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) 是一种安全且简单的方法，让用户使用他们的 Google 账户登录到你的网站或应用程序。 +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) 是一种安全且简化的方式，让用户通过弹窗界面用 Google 账号登录你的网站。 -一旦你设置了 Google 连接器，你将在连接器详情页面看到一个 Google One Tap 卡片。你可以通过切换开关在你的注册和登录页面中启用 Google One Tap。 +设置好 Google 连接器后，你会在连接器详情页看到 Google One Tap 卡片。切换开关即可启用 Google One Tap。 -启用 Google One Tap 后，你可以配置以下选项： +### Google One Tap 配置选项 \{#google-one-tap-configuration-options} -- **如果可能，自动选择凭证**：如果满足 [某些条件](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out)，自动使用 Google 账户登录用户。 -- **如果用户点击/点击外部，取消提示**：如果用户点击或点击提示外部，关闭 Google One Tap 提示。如果禁用，用户必须点击关闭按钮以关闭提示。 -- **在 ITP 浏览器上启用升级的 One Tap UX**：在智能跟踪预防 (ITP) 浏览器上启用升级的 Google One Tap 用户体验。请参考 [此页面](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) 了解更多信息。 +- **如有可能自动选择凭据** - 如果 [满足特定条件](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out)，自动用 Google 账号登录用户 +- **用户点击/触摸外部时取消提示** - 如果用户点击或触摸提示框外部，则关闭 Google One Tap 提示。若禁用，用户需点击关闭按钮来关闭提示。 +- **在 ITP 浏览器上启用升级版 One Tap 体验** - 在智能跟踪防护 (ITP) 浏览器上启用升级版 Google One Tap 用户体验。详见 [官方文档](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers)。 -:::caution -确保在 OAuth 用户授权页面配置中将你的服务器源添加到 **Authorized JavaScript origins** 部分。否则，Google One Tap 无法显示。 +:::warning +请确保你的域名已添加到 OAuth 客户端配置的 **授权的 JavaScript 来源** 部分。否则，Google One Tap 无法显示。 ::: +### Google One Tap 的重要限制 \{#important-limitations-with-google-one-tap} + +如果你同时启用了 **为持久 API 访问存储令牌** 和 **Google One Tap**，你不会自动获得访问令牌或所请求的权限。 + +Google One Tap 登录（不同于标准的“使用 Google 登录”按钮）**不会**颁发 OAuth 访问令牌。它只返回一个 ID 令牌（签名的 JWT），用于验证用户身份，但不授予 API 访问权限。 + +要让 Google One Tap 用户访问 Google API，你可以在用户通过 Google One Tap 登录后，使用 Logto 的 Social Verification API 重新发起联合社交授权 (Authorization) 流程。这允许你按需请求额外权限并更新用户存储的令牌集，无需在 Logto Google 连接器中预先填写这些权限。这种方式实现了增量授权 (Authorization)，只有在你的应用实际需要时才会提示用户额外授权 (Consent)。 + +详细了解 [Google One Tap 的限制](https://developers.google.com/identity/gsi/web/guides/overview) 请参阅官方文档。 + +## 步骤 8：测试并发布你的应用 \{#step-8-test-and-publish-your-app} + +### 针对内部应用 \{#for-internal-apps} + +如果你在 Google 中的 **受众 (Audience)** 类型设置为 **内部**，你的应用仅对你组织内的 Google Workspace 用户可用。你可以用组织内的任意账号进行测试。 + +### 针对外部应用 \{#for-external-apps} + +如果你的 **受众 (Audience)** 类型为 **外部**： + +1. **开发期间**：导航到 **OAuth 用户授权页面 > 测试用户** 并添加测试用户邮箱地址。只有这些用户可以用你的应用登录。 +2. **生产环境**：在 OAuth 用户授权页面部分点击 **发布应用**，让所有拥有 Google 账号的用户都能使用。 + :::note -要在你的网站中启用 Google One Tap（超出 Logto 登录体验），此功能正在开发中。请关注更新。 +具有敏感或受限权限的应用在发布前可能需要 Google 审核。此过程可能需要数周时间。 ::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index 62e51da3ff5..18391876033 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -1,8 +1,8 @@ --- slug: /integrations/oauth2 -sidebar_label: OAuth 2.0 (Social) +sidebar_label: OAuth 2.0（社交） sidebar_custom_props: - description: OAuth 2.0 授权 (Authorization) 框架使第三方应用程序能够获得对 HTTP 服务的有限访问。 + description: OAuth 2.0 授权 (Authorization) 框架使第三方应用能够获得对 HTTP 服务的有限访问权限。 logoFilename: 'oauth.svg' tutorial_name: OAuth2 tutorial_config_name: 标准 OAuth 2.0 应用 @@ -12,24 +12,34 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# 设置 OAuth 2.0 协议的社交登录 +# 设置 OAuth 2.0 协议社交登录 -Logto 的官方 OAuth 2.0 协议连接器。 +官方 Logto OAuth 2.0 协议连接器。 -## 开始使用 \{#get-started} +## 入门指南 \{#get-started} -OAuth 连接器使 Logto 能够连接到支持 OAuth 2.0 协议的任意社交身份提供商。 +OAuth 连接器让 Logto 能够连接任意支持 OAuth 2.0 协议的社交身份提供商。使用 OAuth 连接器，你的应用可以： + +- 添加社交登录按钮 +- 将用户账户与社交身份关联 +- 从社交提供商同步用户资料信息 +- 通过 Logto Secret Vault 安全存储令牌，访问第三方 API，实现自动化任务（如编辑 Google Docs、管理应用内日历事件） + +要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 OAuth 2.0 连接器： + +1. 前往 Logto 控制台 > 连接器 > 社交连接器。 +2. 点击 **添加社交连接器**，选择 **OAuth 2.0**，点击 **下一步**，并按照分步教程完成集成。 :::note -OAuth 连接器是 Logto 中一种特殊的连接器，你可以添加一些基于 OAuth 协议的连接器。 +OAuth 连接器是 Logto 中一种特殊类型的连接器，你可以添加多个基于 OAuth 协议的连接器。 ::: -## 参考 \{#reference} +## 参考资料 \{#reference} OAuth 2.0 授权 (Authorization) 框架 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index 0e83fe2cce8..69fad0a44be 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ ## 创建你的 OAuth 应用 \{#create-your-oauth-app} -当你打开此页面时，我们相信你已经知道要连接哪个社交身份提供商。首先要做的是确认身份提供商支持 OAuth 协议，这是配置有效连接器的前提条件。然后，按照身份提供商的说明注册并创建用于 OAuth 授权的相关应用。 +当你打开此页面时，我们认为你已经知道要连接哪个社交身份提供商。首先要确认该身份提供商是否支持 OAuth 协议，这是配置有效连接器 (Connector) 的前提。然后，按照身份提供商的指引注册并创建用于 OAuth 授权 (Authorization) 的相关应用。 -## 配置你的连接器 \{#configure-your-connector} +## 配置你的连接器 (Connector) \{#configure-your-connector} -出于安全考虑，我们仅支持“授权码”授权类型，并且它可以完美适应 Logto 的场景。 +出于安全考虑，我们仅支持 “Authorization Code” 授权类型，这也完全适用于 Logto 的场景。 -`clientId` 和 `clientSecret` 可以在你的 OAuth 应用详情页面找到。 +`clientId` 和 `clientSecret` 可以在你的 OAuth 应用详情页找到。 -_clientId_：客户端 ID 是一个唯一标识符，用于在注册时识别客户端应用程序。授权服务器使用此 ID 验证客户端应用程序的身份，并将任何授权的访问令牌与该特定客户端应用程序关联。 +_clientId_：client ID 是在向授权服务器注册时用于标识客户端应用程序的唯一标识符。授权服务器使用此 ID 验证客户端应用程序的身份，并将任何已授权的访问令牌 (Access token) 与该特定客户端应用程序关联。 -_clientSecret_：客户端密钥是授权服务器在注册期间发放给客户端应用程序的机密密钥。客户端应用程序使用此密钥在请求访问令牌时向授权服务器进行身份验证。客户端密钥被视为机密信息，应始终保持安全。 +_clientSecret_：client secret 是授权服务器在注册期间发放给客户端应用程序的机密密钥。客户端应用程序在请求访问令牌 (Access token) 时使用此密钥向授权服务器进行身份验证。client secret 属于机密信息，应始终妥善保管。 -_tokenEndpointAuthMethod_：令牌端点认证方法由客户端应用程序在请求访问令牌时用于向授权服务器进行身份验证。要发现支持的方法，请查阅 OAuth 2.0 服务提供商的 OpenID Connect 发现端点中的 `token_endpoint_auth_methods_supported` 字段，或参考 OAuth 2.0 服务提供商提供的相关文档。 +_tokenEndpointAuthMethod_：令牌端点认证方法由客户端应用程序在请求访问令牌 (Access token) 时用于向授权服务器进行身份验证。要了解支持的方法，请查阅 OAuth 2.0 服务提供商的 OpenID Connect 发现端点中的 `token_endpoint_auth_methods_supported` 字段，或参考 OAuth 2.0 服务提供商提供的相关文档。 -_clientSecretJwtSigningAlgorithm (可选)_：仅在 `tokenEndpointAuthMethod` 为 `client_secret_jwt` 时需要。客户端密钥 JWT 签名算法由客户端应用程序用于在令牌请求期间向授权服务器发送的 JWT 进行签名。 +_clientSecretJwtSigningAlgorithm（可选）_：仅当 `tokenEndpointAuthMethod` 为 `client_secret_jwt` 时需要。client secret JWT 签名算法用于客户端应用程序在令牌请求期间对发送给授权服务器的 JWT 进行签名。 -_scope_：权限参数用于指定客户端应用程序请求访问的资源和权限集。权限参数通常定义为一个空格分隔的值列表，代表特定的权限。例如，权限值“read write”可能表示客户端应用程序请求对用户数据的读写访问。 +_scope_：scope 参数用于指定客户端应用程序请求访问的一组资源和权限 (Permissions)。scope 参数通常定义为以空格分隔的值列表，代表特定权限。例如，scope 值为 "read write" 可能表示客户端应用程序请求对用户数据的读取和写入权限。 -你需要在社交供应商的文档中找到 `authorizationEndpoint`、`tokenEndpoint` 和 `userInfoEndpoint`。 +你需要在社交厂商的文档中找到 `authorizationEndpoint`、`tokenEndpoint` 和 `userInfoEndpoint`。 -_authenticationEndpoint_：此端点用于启动认证 (Authentication) 过程。认证 (Authentication) 过程通常涉及用户登录并授权客户端应用程序访问其资源。 +_authenticationEndpoint_：此端点用于启动认证 (Authentication) 流程。认证 (Authentication) 流程通常包括用户登录并授权客户端应用程序访问其资源。 -_tokenEndpoint_：此端点由客户端应用程序用于获取可以用于访问请求资源的访问令牌。客户端应用程序通常向令牌端点发送带有授权类型和授权码的请求以接收访问令牌。 +_tokenEndpoint_：此端点由客户端应用程序用于获取可用于访问所请求资源的访问令牌 (Access token)。客户端应用程序通常向 token 端点发送包含授权类型和授权码的请求，以获取访问令牌 (Access token)。 -_userInfoEndpoint_：此端点由客户端应用程序用于获取有关用户的其他信息，例如他们的全名、电子邮件地址或个人资料图片。用户信息端点通常在客户端应用程序从令牌端点获取访问令牌后访问。 +_userInfoEndpoint_：此端点由客户端应用程序用于获取有关用户的其他信息，例如全名、电子邮件地址或头像。user info 端点通常在客户端应用程序从 token 端点获取访问令牌 (Access token) 后访问。 -Logto 还提供了一个 `profileMap` 字段，用户可以自定义从社交供应商的配置文件中映射，这些配置文件通常不是标准的。键是 Logto 的标准用户配置文件字段名称，相应的值应该是社交配置文件的字段名称。在当前阶段，Logto 只关注社交配置文件中的 'id'、'name'、'avatar'、'email' 和 'phone'，只有 'id' 是必需的，其他是可选字段。 +Logto 还提供了一个 `profileMap` 字段，用户可以自定义社交厂商用户资料的映射（通常不是标准格式）。键为 Logto 标准用户资料字段名，对应的值应为社交资料的字段名。目前，Logto 只关注社交资料中的 'id'、'name'、'avatar'、'email' 和 'phone' 字段，其中只有 'id' 是必填项，其他为可选字段。 -`responseType` 和 `grantType` 在授权码授权类型中只能是固定值，因此我们将它们设为可选，默认值将自动填充。 +`responseType` 和 `grantType` 只能是授权码授权类型的固定值，因此我们将其设为可选，默认值会自动填充。 -例如，你可以找到 [Google 用户配置文件响应](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload)，因此其 `profileMap` 应如下所示： +例如，你可以查看 [Google 用户资料响应](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload)，因此其 `profileMap` 应如下所示： ```json { @@ -41,31 +41,97 @@ Logto 还提供了一个 `profileMap` 字段，用户可以自定义从社交供 :::note -我们提供了一个可选的 `customConfig` 键来放置你的自定义参数。 -每个社交身份提供商可能在 OAuth 标准协议上有自己的变体。如果你想要的社交身份提供商严格遵循 OAuth 标准协议，那么你不需要关心 `customConfig`。 +我们提供了一个可选的 `customConfig` 键用于放置你的自定义参数。 +每个社交身份提供商在 OAuth 标准协议上可能有自己的变体。如果你所需的社交身份提供商严格遵循 OAuth 标准协议，则无需关心 `customConfig`。 ::: ## 配置类型 \{#config-types} -| 名称 | 类型 | 必需 | -| ------------------------- | ----------------------- | ----- | -| authorizationEndpoint | string | true | -| userInfoEndpoint | string | true | -| clientId | string | true | -| clientSecret | string | true | -| tokenEndpointResponseType | enum | false | -| responseType | string | false | -| grantType | string | false | -| tokenEndpoint | string | false | -| scope | string | false | -| customConfig | Record\ | false | -| profileMap | ProfileMap | false | - -| ProfileMap 字段 | 类型 | 必需 | 默认值 | -| --------------- | ------ | ----- | ------ | -| id | string | false | id | -| name | string | false | name | -| avatar | string | false | avatar | -| email | string | false | email | -| phone | string | false | phone | +| 名称 | 类型 | 是否必填 | +| ------------------------- | ----------------------- | -------- | +| authorizationEndpoint | string | true | +| userInfoEndpoint | string | true | +| clientId | string | true | +| clientSecret | string | true | +| tokenEndpointResponseType | enum | false | +| responseType | string | false | +| grantType | string | false | +| tokenEndpoint | string | false | +| scope | string | false | +| customConfig | Record\ | false | +| profileMap | ProfileMap | false | + +| ProfileMap 字段 | 类型 | 是否必填 | 默认值 | +| --------------- | ------ | -------- | ------ | +| id | string | false | id | +| name | string | false | name | +| avatar | string | false | avatar | +| email | string | false | email | +| phone | string | false | phone | + +## 通用设置 \{#general-settings} + +以下是一些不会阻止你连接身份提供商，但可能影响终端用户认证 (Authentication) 体验的通用设置。 + +### 社交按钮名称和 logo \{#social-button-name-and-logo} + +如果你希望在登录页面显示社交按钮，可以设置社交身份提供商的**名称**和**logo**（深色模式和浅色模式）。这将帮助用户识别社交登录选项。 + +### 身份提供商名称 \{#identity-provider-name} + +每个社交连接器 (Connector) 都有唯一的身份提供商 (IdP) 名称，用于区分用户身份。常见连接器 (Connector) 使用固定的 IdP 名称，自定义连接器 (Connector) 需要唯一值。详细了解 [IdP 名称](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name)。 + +### 同步用户资料信息 \{#sync-profile-information} + +在 OAuth 连接器 (Connector) 中，你可以设置同步用户资料（如用户名和头像）的策略。可选项包括： + +- **仅在注册时同步**：用户首次登录时获取一次资料信息。 +- **每次登录时同步**：每次用户登录时都会更新资料信息。 + +### 存储令牌以访问第三方 API（可选） \{#store-tokens-to-access-third-party-apis-optional} + +如果你希望访问身份提供商的 API 并在用户授权 (Authorization) 下执行操作（无论是通过社交登录还是账号绑定），Logto 需要获取特定 API 权限 (Scopes) 并存储令牌 (Tokens)。 + +1. 按上述说明在 **scope** 字段中添加所需权限 (Scopes) +2. 在 Logto OAuth 连接器 (Connector) 中启用 **为持久 API 访问存储令牌**。Logto 会将访问令牌 (Access token) 安全地存储在 Secret Vault 中。 +3. 对于**标准** OAuth/OIDC 身份提供商，必须包含 `offline_access` 权限 (Scope) 以获取刷新令牌 (Refresh token)，防止反复弹出用户授权页面 (Consent screen)。 + +:::warning +请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即在身份提供商的应用设置中生成新密钥。 +::: + +## 使用 OAuth 连接器 (Connector) \{#utilize-the-oauth-connector} + +创建好 OAuth 连接器 (Connector) 并连接到你的身份提供商后，你可以将其集成到终端用户流程中。根据你的需求选择相应选项： + +### 启用社交登录按钮 \{#enable-social-sign-in-button} + +1. 在 Logto 控制台，前往 登录体验 > 注册与登录。 +2. 在 **社交登录** 部分添加 OAuth 连接器 (Connector)，让用户通过你的身份提供商进行认证 (Authentication)。 + +了解更多关于 [社交登录体验](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 绑定或解绑社交账号 \{#link-or-unlink-a-social-account} + +使用 Account API 在你的应用中构建自定义账号中心，让已登录用户绑定或解绑社交账号。[参考 Account API 教程](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以仅为账号绑定和 API 访问启用 OAuth 连接器 (Connector)，而不启用社交登录。 +::: + +### 访问身份提供商 API 并执行操作 \{#access-identity-provider-apis-and-perform-actions} + +你的应用可以从 Secret Vault 检索已存储的访问令牌 (Access token)，调用身份提供商的 API 并自动化后端任务。具体能力取决于你的身份提供商及你请求的权限 (Scopes)。请参考检索存储令牌以访问 API 的指南。 + +## 管理用户社交身份 \{#manage-user-s-social-identity} + +用户绑定社交账号后，管理员可以在 Logto 控制台管理该连接： + +1. 前往 Logto 控制台 > 用户管理 并打开用户资料。 +2. 在 **社交连接** 下找到身份提供商项并点击 **管理**。 +3. 在此页面，管理员可以管理用户的社交连接，查看所有从社交账号授权并同步的资料信息，以及检查访问令牌 (Access token) 状态。 + +:::note +部分身份提供商的访问令牌 (Access token) 响应不包含具体权限 (Scope) 信息，因此 Logto 无法直接显示用户授权 (Authorization) 的权限列表。但只要用户在授权 (Authorization) 时同意了所请求的权限 (Scopes)，你的应用在访问 OAuth API 时就会拥有相应权限 (Permissions)。 +::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index e902e92c4ef..ce05159d724 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -1,8 +1,8 @@ --- slug: /integrations/oidc -sidebar_label: OIDC (社交) +sidebar_label: OIDC（社交） sidebar_custom_props: - description: OpenID Connect 1.0 是 OAuth 2.0 协议之上的一个简单身份层。 + description: OpenID Connect 1.0 是建立在 OAuth 2.0 协议之上的简单身份层。 tutorial_name: OIDC tutorial_config_name: 标准 OIDC 应用 --- @@ -13,17 +13,27 @@ import Integration from './_integration.mdx'; # 设置 OpenID Connect (OIDC) 社交登录 -Logto 的 OpenID Connect (OIDC) 协议官方连接器。 +官方 Logto OpenID Connect (OIDC) 协议连接器。 -## 开始使用 \{#get-started} +## 入门指南 \{#get-started} -OIDC 连接器使 Logto 能够连接到支持 OIDC 协议的任意社交身份提供商 (IdP)。 +OIDC 连接器让 Logto 能够连接到任意支持 OIDC 协议的社交身份提供商 (IdP)。使用 OIDC 连接器，你的应用可以： + +- 添加社交登录按钮 +- 将用户账户与社交身份关联 +- 从社交提供商同步用户资料信息 +- 通过 Logto Secret Vault 安全存储令牌，访问第三方 API，实现自动化任务（如编辑 Google Docs、管理应用中的日历事件） + +要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 OIDC 连接器： + +1. 前往 Logto 控制台 > 连接器 > 社交连接器。 +2. 点击 **添加社交连接器**，选择 **OIDC**，点击 **下一步**，并按照分步教程完成集成。 :::note -OIDC 连接器是 Logto 中一种特殊的连接器，你可以添加一些基于 OIDC 的连接器。 +OIDC 连接器是 Logto 中一种特殊类型的连接器，你可以添加多个基于 OIDC 协议的连接器。 ::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index 9477a688b88..f57326bab46 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,51 +1,51 @@ ## 创建你的 OIDC 应用 \{#create-your-oidc-app} -当你打开此页面时，我们相信你已经知道要连接哪个社交身份提供商。首先要做的是确认身份提供商支持 OIDC 协议，这是配置有效连接器的前提。然后，按照身份提供商的说明注册并创建用于 OIDC 授权的相关应用。 +当你打开此页面时，我们认为你已经知道要连接哪个社交身份提供商。首先需要确认该身份提供商支持 OIDC 协议，这是配置有效连接器的前提。然后，按照身份提供商的指引注册并创建用于 OIDC 授权的相关应用。 ## 配置你的连接器 \{#configure-your-connector} -出于安全考虑，我们仅支持“Authorization Code”授权类型，它可以完美适应 Logto 的场景。 +出于安全考虑，我们仅支持“授权码 (Authorization Code)”授权类型，这也完全适用于 Logto 的场景。 -`clientId` 和 `clientSecret` 可以在你的 OIDC 应用详情页面找到。 +`clientId` 和 `clientSecret` 可以在你的 OIDC 应用详情页找到。 -_clientId_：客户端 ID 是一个唯一标识符，用于在注册时识别客户端应用程序。授权服务器使用此 ID 验证客户端应用程序的身份，并将任何授权的访问令牌与该特定客户端应用程序关联。 +_clientId_：client ID 是在向授权服务器注册时用于标识客户端应用程序的唯一标识符。授权服务器使用此 ID 验证客户端应用程序的身份，并将任何已授权的访问令牌与该特定客户端应用程序关联。 -_clientSecret_：客户端密钥是在注册时由授权服务器发放给客户端应用程序的机密密钥。客户端应用程序使用此密钥在请求访问令牌时向授权服务器进行身份验证。客户端密钥被视为机密信息，应始终保持安全。 +_clientSecret_：client secret 是授权服务器在注册期间发放给客户端应用程序的机密密钥。客户端应用程序在请求访问令牌时使用此密钥向授权服务器进行身份验证。client secret 属于机密信息，应始终妥善保管。 -_tokenEndpointAuthMethod_：令牌端点认证方法用于客户端应用程序在请求访问令牌时向授权服务器进行身份验证。要发现支持的方法，请查阅 OAuth 2.0 服务提供商的 OpenID Connect 发现端点中的 `token_endpoint_auth_methods_supported` 字段，或参考 OAuth 2.0 服务提供商提供的相关文档。 +_tokenEndpointAuthMethod_：令牌端点认证方法用于客户端应用程序在请求访问令牌时向授权服务器进行身份验证。要了解支持的方法，请查阅 OAuth 2.0 服务提供商的 OpenID Connect 发现端点中的 `token_endpoint_auth_methods_supported` 字段，或参考 OAuth 2.0 服务提供商的相关文档。 -_clientSecretJwtSigningAlgorithm (可选)_：仅在 `tokenEndpointAuthMethod` 为 `client_secret_jwt` 时需要。客户端密钥 JWT 签名算法用于客户端应用程序在令牌请求期间向授权服务器发送的 JWT 签名。 +_clientSecretJwtSigningAlgorithm（可选）_：仅当 `tokenEndpointAuthMethod` 为 `client_secret_jwt` 时需要。client secret JWT 签名算法用于客户端应用程序在令牌请求期间对发送给授权服务器的 JWT 进行签名。 -_scope_：权限参数用于指定客户端应用程序请求访问的资源和权限集。权限参数通常定义为一个以空格分隔的值列表，代表特定权限。例如，权限值“read write”可能表示客户端应用程序请求对用户数据的读写访问。 +_scope_：scope 参数用于指定客户端应用程序请求访问的一组资源和权限。scope 参数通常定义为以空格分隔的值列表，代表特定权限。例如，scope 值为 "read write" 可能表示客户端应用程序请求对用户数据的读写访问权限。 -你需要找到 `authorizationEndpoint`、`tokenEndpoint`、`jwksUri` 和 `issuer` 作为 OpenID 提供商的配置信息。它们应该在社交供应商的文档中可用。 +你需要找到 `authorizationEndpoint`、`tokenEndpoint`、`jwksUri` 和 `issuer` 作为 OpenID Provider 的配置信息。这些信息应在社交厂商的文档中可以找到。 -_authenticationEndpoint_：此端点用于启动认证 (Authentication) 过程。认证 (Authentication) 过程通常涉及用户登录并授权客户端应用程序访问其资源。 +_authenticationEndpoint_：此端点用于启动认证 (Authentication) 过程。认证 (Authentication) 过程通常包括用户登录并授权客户端应用程序访问其资源。 -_tokenEndpoint_：此端点由客户端应用程序用于获取可以访问请求资源的 ID 令牌。客户端应用程序通常向令牌端点发送带有授权类型和授权代码的请求以接收 ID 令牌。 +_tokenEndpoint_：此端点由客户端应用程序用于获取可用于访问所请求资源的 id token。客户端应用程序通常会携带授权类型和授权码向 token 端点发送请求以获取 id token。 -_jwksUri_：这是可以获取社交身份提供商（简称 IdP）的 JSON Web Key Set (JWKS) 的 URL 端点。JWKS 是一组加密密钥，IdP 用于签署和验证在认证 (Authentication) 过程中发放的 JSON Web Tokens (JWTs)。`jwksUri` 由依赖方 (RP) 用于获取 IdP 用于签署 JWT 的公钥，以便 RP 可以验证从 IdP 接收到的 JWT 的真实性和完整性。 +_jwksUri_：这是可以获取社交身份提供商（简称 IdP）的 JSON Web Key Set (JWKS) 的 URL 端点。JWKS 是一组加密密钥，IdP 用于签名和验证在认证 (Authentication) 过程中签发的 JSON Web Token (JWT)。`jwksUri` 被依赖方（RP）用于获取 IdP 用于签名 JWT 的公钥，以便 RP 验证从 IdP 接收到的 JWT 的真实性和完整性。 -_issuer_：这是 IdP 的唯一标识符，RP 用于验证从 IdP 接收到的 JWT。它包含在 JWT 中作为 `iss` [声明](https://www.rfc-editor.org/rfc/rfc7519#section-4)（ID 令牌始终是 JWT）。发行者值应与 IdP 的授权服务器的 URL 匹配，并且应为 RP 信任的 URI。当 RP 接收到 JWT 时，它会检查 `iss` 声明以确保它是由受信任的 IdP 发放的，并且 JWT 是用于与 RP 一起使用的。 +_issuer_：这是 IdP 的唯一标识符，RP 用于验证从 IdP 接收到的 JWT。它作为 JWT 的 `iss` [声明 (Claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4)（Id token 始终为 JWT）包含在内。issuer 值应与 IdP 授权服务器的 URL 匹配，并且应为 RP 信任的 URI。当 RP 收到 JWT 时，会检查 `iss` 声明 (Claim) 以确保其由受信任的 IdP 签发，并且该 JWT 是为 RP 使用而签发的。 -`jwksUri` 和 `issuer` 一起为 RP 在认证 (Authentication) 过程中验证终端用户的身份提供了安全机制。通过使用从 `jwksUri` 获取的公钥，RP 可以验证 IdP 发放的 JWT 的真实性和完整性。发行者值确保 RP 仅接受由受信任的 IdP 发放的 JWT，并且 JWT 是用于与 RP 一起使用的。 +`jwksUri` 和 `issuer` 共同为 RP 在认证 (Authentication) 过程中验证终端用户身份提供了安全机制。通过使用从 `jwksUri` 获取的公钥，RP 可以验证 IdP 签发的 JWT 的真实性和完整性。issuer 值确保 RP 只接受由受信任 IdP 签发且用于 RP 的 JWT。 -由于始终需要认证 (Authentication) 请求，因此提供了 `authRequestOptionalConfig` 来包装所有可选配置，你可以在 [OIDC 认证 (Authentication) 请求](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 中找到详细信息。你可能还会发现此配置中缺少 `nonce`。由于 `nonce` 应在每个请求中相同，我们将 `nonce` 的生成放在代码实现中。所以不用担心！前面提到的 `jwksUri` 和 `issuer` 也包含在 `idTokenVerificationConfig` 中。 +由于每次都需要认证请求，因此我们提供了 `authRequestOptionalConfig` 用于包装所有可选配置，详细内容可参考 [OIDC 认证请求 (Authentication Request)](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)。你可能会注意到此配置中没有 `nonce`。由于 `nonce` 应该每次请求都不同，我们将 `nonce` 的生成放在代码实现中，所以不用担心！前面提到的 `jwksUri` 和 `issuer` 也包含在 `idTokenVerificationConfig` 中。 -你可能会好奇为什么标准 OIDC 协议支持隐式和混合流，而 Logto 连接器仅支持授权流。已确定隐式和混合流不如授权流安全。由于 Logto 专注于安全性，它仅支持授权流，以为其用户提供最高级别的安全性，尽管其便利性略低。 +你可能会好奇，为什么标准 OIDC 协议支持隐式和混合流，而 Logto 连接器只支持授权码流。经过验证，隐式和混合流的安全性低于授权码流。由于 Logto 注重安全性，因此仅支持授权码流，以为用户提供最高级别的安全性，尽管这可能略微不便。 -`responseType` 和 `grantType` 只能是“Authorization Code”流的固定值，因此我们将它们设为可选，默认值将自动填充。 +`responseType` 和 `grantType` 在“授权码 (Authorization Code)”流中只能为固定值，因此我们将它们设为可选，默认值会自动填充。 :::note -对于所有流类型，我们提供了一个可选的 `customConfig` 键来放置你的自定义参数。 -每个社交身份提供商可能在 OIDC 标准协议上有自己的变体。如果你所需的社交身份提供商严格遵循 OIDC 标准协议，那么你不需要关心 `customConfig`。 +对于所有流类型，我们都提供了可选的 `customConfig` 键用于放置你的自定义参数。 +每个社交身份提供商在 OIDC 标准协议上可能有自己的变体。如果你选择的社交身份提供商严格遵循 OIDC 标准协议，则无需关心 `customConfig`。 ::: ## 配置类型 \{#config-types} -| 名称 | 类型 | 必需 | +| 名称 | 类型 | 必填 | | ------------------------- | ------------------------- | ---- | | scope | string | 是 | | clientId | string | 是 | @@ -56,7 +56,7 @@ _issuer_：这是 IdP 的唯一标识符，RP 用于验证从 IdP 接收到的 J | authRequestOptionalConfig | AuthRequestOptionalConfig | 否 | | customConfig | Record\ | 否 | -| AuthRequestOptionalConfig 属性 | 类型 | 必需 | +| AuthRequestOptionalConfig 属性 | 类型 | 必填 | | ------------------------------ | ------ | ---- | | responseType | string | 否 | | tokenEndpoint | string | 否 | @@ -69,7 +69,7 @@ _issuer_：这是 IdP 的唯一标识符，RP 用于验证从 IdP 接收到的 J | loginHint | string | 否 | | acrValues | string | 否 | -| IdTokenVerificationConfig 属性 | 类型 | 必需 | +| IdTokenVerificationConfig 属性 | 类型 | 必填 | | ------------------------------ | ---------------------------------- | ---- | | jwksUri | string | 是 | | issuer | string \| string[] | 否 | @@ -82,4 +82,70 @@ _issuer_：这是 IdP 的唯一标识符，RP 用于验证从 IdP 接收到的 J | subject | string | 否 | | typ | string | 否 | -查看 [这里](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) 以获取有关 `IdTokenVerificationConfig` 的更多详细信息。 +更多关于 `IdTokenVerificationConfig` 的详细信息请参见 [这里](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md)。 + +## 通用设置 \{#general-settings} + +以下是一些不会阻止你连接身份提供商但可能影响终端用户认证 (Authentication) 体验的通用设置。 + +### 社交按钮名称和 Logo \{#social-button-name-and-logo} + +如果你希望在登录页面展示社交按钮，可以设置社交身份提供商的**名称**和**Logo**（深色模式和浅色模式）。这有助于用户识别社交登录选项。 + +### 身份提供商名称 \{#identity-provider-name} + +每个社交连接器都有唯一的身份提供商 (IdP) 名称，用于区分用户身份。常见连接器使用固定的 IdP 名称，自定义连接器则需要唯一值。详细了解 [IdP 名称](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name)。 + +### 同步资料信息 \{#sync-profile-information} + +在 OIDC 连接器中，你可以设置同步资料信息（如用户名和头像）的策略。可选项包括： + +- **仅在注册时同步**：用户首次登录时获取一次资料信息。 +- **每次登录时都同步**：每次用户登录时都会更新资料信息。 + +### 存储令牌以访问第三方 API（可选） \{#store-tokens-to-access-third-party-apis-optional} + +如果你希望访问身份提供商的 API 并在用户授权下执行操作（无论是通过社交登录还是账户绑定），Logto 需要获取特定 API 权限 (Scope) 并存储令牌。 + +1. 按上述说明在 **scope** 字段中添加所需权限 (Scope) +2. 在 Logto OIDC 连接器中启用**为持久 API 访问存储令牌**。Logto 会将访问令牌安全地存储在 Secret Vault 中。 +3. 对于**标准** OAuth/OIDC 身份提供商，必须包含 `offline_access` 权限 (Scope) 以获取刷新令牌 (Refresh token)，避免重复请求用户授权。 + +:::warning +请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即在身份提供商的应用设置中生成新的密钥。 +::: + +## 使用 OIDC 连接器 \{#utilize-the-oidc-connector} + +创建好 OIDC 连接器并连接到你的身份提供商后，你可以将其集成到终端用户流程中。根据你的需求选择相应选项： + +### 启用社交登录按钮 \{#enable-social-sign-in-button} + +1. 在 Logto 控制台，进入 登录体验 > 注册与登录。 +2. 在**社交登录**部分添加 OIDC 连接器，让用户通过你的身份提供商进行认证 (Authentication)。 + +了解更多关于 [社交登录体验](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 绑定或解绑社交账户 \{#link-or-unlink-a-social-account} + +使用 Account API 在你的应用中构建自定义账户中心，让已登录用户绑定或解绑社交账户。[参考 Account API 教程](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +允许仅为账户绑定和 API 访问启用 OIDC 连接器，而不启用社交登录。 +::: + +### 访问身份提供商 API 并执行操作 \{#access-identity-provider-apis-and-perform-actions} + +你的应用可以从 Secret Vault 获取已存储的访问令牌，调用身份提供商的 API 并自动化后端任务。具体能力取决于你的身份提供商及你请求的权限 (Scope)。请参考检索存储令牌以访问 API 的指南。 + +## 管理用户的社交身份 \{#manage-user-s-social-identity} + +用户绑定社交账户后，管理员可以在 Logto 控制台管理该连接： + +1. 进入 Logto 控制台 > 用户管理 并打开用户资料页。 +2. 在**社交连接**下找到身份提供商项并点击**管理**。 +3. 在此页面，管理员可以管理用户的社交连接，查看所有从社交账户授权并同步的资料信息，以及检查访问令牌状态。 + +:::note +部分身份提供商的访问令牌响应不包含具体权限 (Scope) 信息，因此 Logto 无法直接展示用户授权的权限列表。但只要用户在授权时同意了所请求的权限 (Scope)，你的应用在访问 OIDC API 时就会拥有相应权限。 +::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index 25086075bc8..21a4ff35855 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,9 +2,9 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: 在 Google 生态系统中统一和安全地管理用户访问。 + description: 在 Google 生态系统内统一且安全地管理用户访问。 logoFilename: 'google.svg' -tutorial_name: Google Workspace enterprise SSO +tutorial_name: Google Workspace 企业单点登录 (SSO) tutorial_config_name: Google Cloud Platform --- @@ -16,22 +16,23 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; # 设置 Google Workspace 单点登录 (SSO) -通过最少的配置工作，此连接器允许与 Microsoft Entra ID 集成以实现企业单点登录 (SSO)。 +只需极少的配置工作，此连接器即可与 Microsoft Entra ID 集成，实现企业单点登录 (SSO)。 -## 步骤 1：在 Google Cloud Platform 上创建一个新项目 \{#step-1-create-a-new-project-on-google-cloud-platform} +## 步骤 1：在 Google Cloud Platform 上创建新项目 \{#step-1-create-a-new-project-on-google-cloud-platform} -## 步骤 2：为你的应用程序配置用户授权页面 \{#step-2-config-the-consent-screen-for-your-application} +## 步骤 2：为你的应用配置用户授权页面 (Consent screen) \{#step-2-config-the-consent-screen-for-your-application} -## 步骤 3：创建一个新的 OAuth 凭证 \{#step-3-create-a-new-oauth-credential} +## 步骤 3：创建新的 OAuth 凭证 \{#step-3-create-a-new-oauth-credential} @@ -43,6 +44,10 @@ import Step6 from './_step-6.mdx'; -## 步骤 6：设置电子邮件域并启用 SSO 连接器 \{#step-6-set-email-domains-and-enable-the-sso-connector} +## 步骤 6：存储令牌以访问 Google API（可选） \{#step-6-store-tokens-to-access-google-apis-optional} + +## 步骤 7：设置邮箱域并启用 SSO 连接器 \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index a6155a6365d..df024cbaf5a 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,20 +4,21 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -### 步骤 1：在 Google Cloud Platform 上创建一个新项目 \{#step-1-create-a-new-project-on-google-cloud-platform} +### 步骤 1：在 Google Cloud Platform 上创建新项目 \{#step-1-create-a-new-project-on-google-cloud-platform} -### 步骤 2：为你的应用程序配置用户授权页面 \{#step-2-config-the-consent-screen-for-your-application} +### 步骤 2：为你的应用配置用户授权页面 (Consent screen) \{#step-2-config-the-consent-screen-for-your-application} -### 步骤 3：创建一个新的 OAuth 凭证 \{#step-3-create-a-new-oauth-credential} +### 步骤 3：创建新的 OAuth 凭证 \{#step-3-create-a-new-oauth-credential} -### 步骤 4：使用客户端凭证设置 Logto 连接器 \{#step-4-set-up-logto-connector-with-the-client-credentials} +### 步骤 4：使用客户端凭证设置 Logto 连接器 (Connector) \{#step-4-set-up-logto-connector-with-the-client-credentials} @@ -25,6 +26,10 @@ import Step6 from './_step-6.mdx'; -### 步骤 6：设置电子邮件域并启用 SSO 连接器 \{#step-6-set-email-domains-and-enable-the-sso-connector} +### 步骤 6：存储令牌以访问 Google API（可选） \{#step-6-store-tokens-to-access-google-apis-optional} + +### 步骤 7：设置邮箱域并启用 SSO 连接器 (Connector) \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index 9145b653b9e..81c965b0e71 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -使用 `Scope` 字段向你的 OAuth 请求添加额外的权限 (Scopes)。这将允许你从 Google OAuth 服务器请求更多信息。请参考 [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) 文档以获取更多信息。 +Scope（权限）定义了你的应用向用户请求的权限，并控制你的应用可以从他们的 Google Workspace 账户访问哪些数据。请求 Google 权限需要在双方进行配置： -无论自定义权限 (Scope) 设置如何，Logto 总是会向身份提供商 (IdP) 发送 `openid`、`profile` 和 `email` 权限 (Scopes)。这是为了确保 Logto 能够正确检索用户的身份信息和电子邮件地址。 +**在 Google Cloud Console 中：** + +1. 导航到 **APIs & Services > OAuth consent screen > Scopes**。 +2. 点击 **Add or Remove Scopes**，并仅选择你的应用所需的 scope（权限）： + - 认证 (Authentication)（必需）： + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - API 访问（可选）：添加你的应用所需的其他 scope（权限）（例如 Drive、Calendar、YouTube）。浏览 [Google API Library](https://console.cloud.google.com/apis/library) 以查找可用服务。如果你的应用需要访问除基础权限外的 Google API，请先在 Google API Library 中启用你的应用将使用的特定 API（如 Google Drive API、Gmail API、Calendar API）。 +3. 点击 **Update** 确认选择。 +4. 点击 **Save and Continue** 应用更改。 + +**在 Logto Google Workspace 连接器 (Connector) 中：** + +1. Logto 会自动包含 `openid`、`profile` 和 `email` scope（权限），以获取基础用户身份信息。如果你只需要基础用户信息，可以将 `Scopes` 字段留空。 +2. 在 `Scopes` 字段中添加额外的 scope（权限）（用空格分隔），以从 Google 请求更多数据。请使用完整的 scope URL，例如：`https://www.googleapis.com/auth/calendar.readonly` + +:::tip +如果你的应用请求这些 scope（权限）以访问 Google API 并执行操作，请确保在 Logto Google 连接器 (Connector) 中启用 **Store tokens for persistent API access**。详情请参见下一节。 +::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index f0ade9ae727..81e155e21dd 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -在 Logto 的连接器 `SSO 体验` 标签中提供你组织的 `电子邮件域`。这将启用 SSO 连接器作为这些用户的认证 (Authentication) 方法。 +如果你想访问 [Google APIs](https://console.cloud.google.com/apis/library) 并在用户授权 (Authorization) 下执行操作，Logto 需要获取特定的 API 权限 (Scopes) 并存储令牌。 -具有指定域的电子邮件地址的用户将被重定向，以使用你的 SSO 连接器作为他们唯一的认证 (Authentication) 方法。 +1. 在你的 Google Cloud Console OAuth 用户授权页面 (Consent screen) 配置和 Logto Google 连接器中添加所需的权限 (Scopes)。 +2. 在 Logto Google 连接器中启用 **为持久 API 访问存储令牌**。Logto 会将 Google 访问令牌 (Access token) 和刷新令牌 (Refresh token) 安全地存储在 Secret Vault 中。 +3. 为确保返回刷新令牌 (Refresh token)，请在 Logto Google 连接器中启用 **离线访问 (Offline Access)**。 -有关 Google Workspace SSO 连接器的更多信息，请查看 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect)。 +:::warning +你不需要在 Logto 的 `Scope` 字段中添加 `offline_access` —— 这样做可能会导致错误。当启用离线访问 (Offline Access) 时，Google 会自动使用 `access_type=offline`。 +::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..92134a25ede --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +在 Logto 的连接器 `SSO 体验` 标签页中填写你组织的 `email domains`。这将为这些用户启用 SSO 连接器作为认证 (Authentication) 方法。 + +拥有指定域名邮箱地址的用户将被重定向，仅能使用你的 SSO 连接器作为他们唯一的认证 (Authentication) 方法。 + +关于 Google Workspace SSO 连接器的更多信息，请参阅 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 1081945e7b4..c51aa69fe6c 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -1,10 +1,10 @@ --- slug: /integrations/oidc-sso -sidebar_label: OIDC (企业) +sidebar_label: OIDC（企业） sidebar_custom_props: description: 基于 OAuth 2.0 构建的现代协议，用于 Web 和移动应用中的身份验证。 logoFilename: 'oidc.svg' -tutorial_name: OIDC enterprise SSO +tutorial_name: OIDC 企业单点登录 (SSO) tutorial_config_name: 在你的身份提供商 (IdP) 上配置 OIDC 应用 --- @@ -13,10 +13,12 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; # 设置 OpenID Connect (OIDC) 单点登录 (SSO) -通过最少的配置工作，此连接器允许与任何基于 OIDC 的身份提供商 (IdP) 集成。 +通过极简配置，这个连接器可以让你集成任何基于 OIDC 的身份提供商 (IdP)。 @@ -28,6 +30,14 @@ import Step3 from './_step-3.mdx'; -## 步骤 3：设置电子邮件域并启用 SSO 连接器 \{#step-3-set-email-domains-and-enable-the-sso-connector} +## 步骤 3：配置权限 (Scopes)（可选） \{#step-3-configure-scopes-optional} + +## 步骤 4：存储令牌以访问第三方 API（可选） \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## 步骤 5：设置邮箱域名并启用 SSO 连接器 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index 307608b8a30..63cfcd9a57e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,8 +1,10 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; -### 步骤 1：在你的身份提供商 (IdP) 上创建一个 OIDC 应用程序 \{#step-1-create-an-oidc-application-on-your-idp} +### 步骤 1：在你的身份提供商 (IdP) 上创建 OIDC 应用 \{#step-1-create-an-oidc-application-on-your-idp} @@ -10,6 +12,14 @@ import Step3 from './_step-3.mdx'; -### 步骤 3：设置电子邮件域并启用 SSO 连接器 \{#step-3-set-email-domains-and-enable-the-sso-connector} +## 步骤 3：配置权限 (Scopes)（可选） \{#step-3-configure-scopes-optional} + +## 步骤 4：存储令牌以访问第三方 API（可选） \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## 步骤 5：设置邮箱域并启用 SSO 连接器 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index 5220aa167a2..bfd524014d2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -在 IdP 端成功创建 OIDC 应用程序后，你需要将 IdP 配置反馈给 Logto。导航到 `Connection` 选项卡，并填写以下配置： +在 IdP 端成功创建 OIDC 应用后，你需要将 IdP 的配置信息返回给 Logto。前往 `Connection` 标签页，并填写以下配置信息： -- **Client ID**：由 IdP 分配给你的 OIDC 应用程序的唯一标识符。Logto 使用此标识符在 OIDC 流程中识别和认证应用程序。 -- **Client Secret**：在 Logto 和 IdP 之间共享的机密密钥。此密钥用于认证 OIDC 应用程序并保护 Logto 和 IdP 之间的通信。 -- **发行者 (Issuer)**：发行者 URL，是 IdP 的唯一标识符，指定可以找到 OIDC 身份提供商的位置。它是 OIDC 配置的重要组成部分，因为它帮助 Logto 发现必要的端点。 - 为了简化配置过程，Logto 将自动获取所需的 OIDC 端点和配置。这是通过利用你提供的发行者并调用 IdP 的 OIDC 发现端点来完成的。确保发行者端点有效且配置准确，以便 Logto 能够正确检索所需信息。 - 在成功获取请求后，你应该能够在发行者部分看到解析后的 IdP 配置。 -- **权限 (Scope)**：一个以空格分隔的字符串列表，定义 Logto 在 OIDC 认证 (Authentication) 过程中请求的所需权限或访问级别。权限 (Scope) 参数允许你指定 Logto 从 IdP 请求哪些信息和访问权限。 - 权限 (Scope) 参数是可选的。无论自定义权限设置如何，Logto 总是会向 IdP 发送 `openid`、`profile` 和 `email` 权限 (Scopes)。 - 这是为了确保 Logto 能够正确从 IdP 检索用户的身份信息和电子邮件地址。你可以在权限 (Scope) 参数中添加其他权限，以请求更多来自 IdP 的信息。 +- **Client ID**：由 IdP 分配给你的 OIDC 应用的唯一标识符。Logto 使用此标识符在 OIDC 流程中识别并认证该应用。 +- **Client Secret**：Logto 与 IdP 之间共享的机密密钥。此密钥用于认证 OIDC 应用，并保障 Logto 与 IdP 之间的通信安全。 +- **发行者 (Issuer)**：发行者 (Issuer) URL，是 IdP 的唯一标识符，指定了可以找到 OIDC 身份提供商 (IdP) 的位置。它是 OIDC 配置中的关键部分，有助于 Logto 发现所需的端点。 + 为了简化配置流程，Logto 会自动获取所需的 OIDC 端点和配置信息。这是通过你提供的发行者 (Issuer) 并调用 IdP 的 OIDC 发现端点来实现的。务必确保发行者 (Issuer) 端点有效且配置准确，以便 Logto 能正确获取所需信息。 + 成功获取后，你应该可以在发行者 (Issuer) 部分看到解析后的 IdP 配置信息。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index b48a78e7b43..b5ec537cf68 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -在 Logto 的连接器 `SSO 体验` 标签上提供你组织的 `电子邮件域`。这将启用 SSO 连接器作为这些用户的认证 (Authentication) 方法。 +权限 (Scopes) 定义了你的应用从用户请求哪些权限，并控制你的应用可以从他们的企业账户访问哪些数据。 -具有指定域的电子邮件地址的用户将被重定向，以使用你的 SSO 连接器作为他们唯一的认证 (Authentication) 方法。 +设置权限 (Scopes) 需要在双方进行配置： + +1. **你的身份提供商 (IdP)**：在 IdP 控制台中配置哪些权限允许用于授权 (Authorization) + - 某些 IdP 默认启用所有公共权限 (Scopes)（无需操作） + - 其他 IdP 需要你显式授予权限 +2. **Logto 企业连接器**：在 Logto OIDC 企业连接器设置 > `Scopes` 字段中，指定在认证 (Authentication) 过程中要请求哪些权限 (Scopes)。 + - Logto 总是包含 `openid`、`profile` 和 `email` 权限 (Scopes)，以获取基本的用户身份信息，无论你的自定义权限 (Scopes) 设置如何。 + - 你可以添加其他权限 (Scopes)（用空格分隔），以从 IdP 请求更多信息。 + +:::tip +如果你的应用需要使用这些权限 (Scopes) 访问 API，请确保在 Logto 企业连接器中启用 **为持久 API 访问存储令牌**。详情请参见下一节。 +::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..cb82e0014ce --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +如果你想访问身份提供商 (IdP) 的 API 并在用户授权 (Authorization) 下执行操作，Logto 需要获取特定的 API 权限 (Scopes) 并存储令牌。 + +1. 按照上述说明，在 **scope** 字段中添加所需的权限 (Scopes) +2. 在 Logto OIDC 企业连接器中启用 **为持久 API 访问存储令牌**。Logto 会将访问令牌 (Access tokens) 安全地存储在 Secret Vault 中。 +3. 对于 **标准** OIDC 身份提供商 (IdP)，必须包含 `offline_access` 权限 (Scope) 以获取刷新令牌 (Refresh token)，从而避免反复提示用户授权 (Consent)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..28e6c76b2a9 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +在 Logto 的连接器 `SSO 体验` 选项卡中提供你组织的 `email domains`。这将为这些用户启用 SSO 连接器作为认证 (Authentication) 方法。 + +属于指定域名的邮箱用户将被重定向，仅能使用你的 SSO 连接器作为他们唯一的认证 (Authentication) 方法。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index 0e833c6a6ef..fa541b8117d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -2,40 +2,44 @@ sidebar_position: 2 --- -# 部署和配置 +# 部署与配置 -在上一篇文章中，我们介绍了[快速开始使用 Logto](/logto-oss/get-started-with-oss)的基础知识。本文将深入探讨在生产环境中部署 Logto 的最佳实践和详细配置步骤。 +在上一篇文章中，我们介绍了[快速开始使用 Logto](/logto-oss/get-started-with-oss)的基础内容。本文将深入探讨，将重点放在生产环境中部署 Logto 的最佳实践和详细配置步骤上。 ## 环境变量 \{#environment-variables} -我们在演示中使用了生成的环境变量预设 (`docker-compose.yml`)，你应该用自己的变量替换它们，并在多个 Logto 实例中保持一致。 +我们在演示中（`docker-compose.yml`）使用了生成的环境变量预设，你应该用你自己的变量替换它们，并在多个 Logto 实例之间保持一致。 -你可以直接设置环境变量，或者将 `.env` 文件放在 Logto 项目的根目录中。如果你使用 Docker 进行测试，请查看镜像在 `/etc/logto` 中生成的 `.env`。 +你可以直接设置环境变量，或者在 Logto 项目根目录下放置一个 `.env` 文件。如果你在使用 Docker 进行测试，可以查看镜像在 `/etc/logto` 目录下生成的 `.env` 文件。 -### 基本要素 \{#essentials} +### 基本项 \{#essentials} - `DB_URL` Logto 数据库的 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 -- `PORT` Logto 监听的端口。默认 `3001`。 -- `ENDPOINT` 你可以为生产环境指定一个带有自定义域名的 URL（例如 `ENDPOINT=https://logto.domain.com`）。这也会影响 [OIDC 发行者标识符](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 +- `PORT` Logto 监听的端口。默认值为 `3001`。 +- `ENDPOINT` 你可以为生产环境指定自定义域名的 URL（例如：`ENDPOINT=https://logto.domain.com`）。这也会影响 [OIDC 发行者 (Issuer) 标识符](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 **启用管理控制台** -- `ADMIN_PORT` Logto 管理控制台监听的端口。默认 `3002`。 -- `ADMIN_ENDPOINT` 你可以为生产环境指定一个带有自定义域名的 URL（例如 `ADMIN_ENDPOINT=https://admin.domain.com`）。这也会影响管理控制台重定向 URI 的值。 +- `ADMIN_PORT` Logto 管理控制台监听的端口。默认值为 `3002`。 +- `ADMIN_ENDPOINT` 你可以为生产环境指定自定义域名的 URL（例如：`ADMIN_ENDPOINT=https://admin.domain.com`）。这也会影响管理控制台重定向 URI 的值。 **禁用管理控制台** -- `ADMIN_DISABLE_LOCALHOST` 设置为 `1` 或 `true` 以关闭管理控制台的端口。如果未设置 `ADMIN_ENDPOINT`，它将完全禁用管理控制台。 +- `ADMIN_DISABLE_LOCALHOST` 设置为 `1` 或 `true` 可关闭管理控制台端口。如果未设置 `ADMIN_ENDPOINT`，将完全禁用管理控制台。 -有关环境变量的更多详细信息，请参阅[配置](/concepts/core-service/configuration/)。 +有关环境变量的更多详情，请参阅 [配置](/concepts/core-service/configuration/)。 + +**启用 Secret Vault** + +- 要使用 [Secret Vault](/secret-vault)，你需要将 `SECRET_VAULT_KEK` 设置为你的密钥加密密钥（KEK）的 base64 编码字符串。它用于加密 Secret Vault 中的数据加密密钥（DEK）。推荐使用 AES-256（32 字节）。示例：`crypto.randomBytes(32).toString('base64')`。 ### HTTPS \{#https} -你可以使用 Node.js 直接提供 HTTPS 服务，或者在 Node.js 前设置 HTTPS 代理 / 负载均衡器。有关详细信息，请参阅[启用 HTTPS](/concepts/core-service/configuration/#enabling-https)。 +你可以直接使用 Node.js 提供 HTTPS 服务，或者在 Node.js 前面设置 HTTPS 代理 / 负载均衡器。详情见 [启用 HTTPS](/concepts/core-service/configuration/#enabling-https)。 ### 反向代理 \{#reverse-proxy} -如果你想在服务器上使用反向代理，例如 Nginx 或 Apache，你需要在代理传递设置中分别映射 3001 和 3002 端口。假设你使用 Nginx，Logto 认证 (Authentication) 端点运行在端口 3001，Logto 管理控制台运行在 3002，请在 nginx.conf 中放置以下配置： +如果你想在服务器上使用反向代理，例如 Nginx 或 Apache，你需要在代理转发设置中分别映射 3001 和 3002 端口。假设你使用 Nginx，Logto 认证 (Authentication) 端点运行在 3001 端口，Logto 管理控制台运行在 3002 端口，在 nginx.conf 中加入如下配置： ``` server { @@ -87,15 +91,15 @@ server { nginx -s reload ``` -一切就绪。打开浏览器并访问 `https://admin.your-domain.com`，你应该能够看到 Logto 欢迎页面。 +一切就绪。打开浏览器访问 `https://admin.your-domain.com`，你应该能看到 Logto 欢迎页面。 ## 容器化 \{#containerization} -对于生产环境，你可以使用 Docker 将 Logto 容器化。你可以在项目的根目录中找到 Dockerfile。如果你想运行多个 Logto 实例，例如在 Kubernetes 集群中部署 Logto，需要采取一些额外的步骤。 +在生产环境中，你可以使用 Docker 对 Logto 进行容器化。你可以在项目根目录找到 Dockerfile。如果你想运行多个 Logto 实例，比如在 Kubernetes 集群中部署 Logto，还需要进行一些额外的操作。 -### 共享连接器文件夹 \{#shared-connectors-folder} +### 共享连接器 (Connectors) 文件夹 \{#shared-connectors-folder} -默认情况下，Logto 会在 `core` 文件夹的根目录中创建一个 `connectors` 文件夹。我们建议在多个 Logto 实例之间共享该文件夹，你需要将 `packages/core/connectors` 文件夹挂载到容器中，并运行 `npm run cli connector add -- --official` 来部署连接器。 +默认情况下，Logto 会在 `core` 文件夹的根目录下创建一个 `connectors` 文件夹。我们建议在多个 Logto 实例之间共享该文件夹，你需要将 `packages/core/connectors` 文件夹挂载到容器，并运行 `npm run cli connector add -- --official` 来部署连接器 (Connectors)。 以下是 Kubernetes 的一个最小示例 `deployment`： @@ -130,21 +134,21 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -在这个示例中，我们创建了一个空目录作为卷并将其挂载到容器中。然后我们在初始化容器中运行 `npm run cli connector add -- --official` 来下载连接器。最后，每个容器将共享同一个包含我们官方连接器的连接器文件夹。 +在这个例子中，我们创建了一个空目录作为卷并挂载到容器。然后在 init 容器中运行 `npm run cli connector add -- --official` 下载连接器 (Connectors)。最后，每个容器都会共享同一个已包含官方连接器 (Connectors) 的文件夹。 :::note -这是一个示例 yaml，为了运行 Logto，你需要正确设置环境变量。 +这是一个示例 yaml，实际运行 Logto 时需要正确设置环境变量。 ::: -对于生产环境，你可以将“空目录”卷替换为持久卷，并以自己的方式完成“初始化”任务，你知道自己在做什么！ +在生产环境中，你可以将 "empty dir" 卷替换为持久卷，并用你自己的方式完成 "init" 操作，你知道你在做什么！ ### 数据库变更 \{#database-alteration} -与连接器类似，数据库变更需要在单个实例中运行。你可以使用一个作业来运行变更脚本。 +与连接器 (Connectors) 类似，数据库变更需要在单个实例中运行。你可以使用 job 来运行变更脚本。 -在非交互式运行变更时，`CI=true` 环境变量是必要的。 +当以非交互方式运行变更时，`CI=true` 环境变量是必需的。 ```yaml apiVersion: batch/v1 @@ -171,4 +175,4 @@ spec: restartPolicy: Never ``` -有关变更命令的详细信息，请参阅[数据库变更](/logto-oss/using-cli/database-alteration/)。 +关于变更命令的详细信息，请参阅 [数据库变更](/logto-oss/using-cli/database-alteration/)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..6058320c111 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# 密钥保险库 (Secret Vault) + +Logto 的密钥保险库 (Secret Vault) 旨在安全存储敏感的用户数据——如访问令牌 (Access tokens)、API 密钥、验证码或任何其他需要保护的机密信息。这些密钥通常用于代表用户访问第三方服务，因此安全存储至关重要。 + +## 加密方案 \{#encryption-scheme} + +为了保护敏感数据，密钥保险库 (Secret Vault) 采用了基于**数据加密密钥 (DEK)** 和**密钥加密密钥 (KEK)** 的强大加密方案。 + +- **每个密钥单独加密**：每个密钥都使用其唯一的 DEK 进行加密，即使某个密钥被泄露，其他密钥依然安全。 +- **密钥包裹**：DEK 本身会被 KEK 加密（或“包裹”），KEK 由系统安全管理和存储。 +- **分层安全**：这种两层加密方式确保即使系统部分被攻破，攻击者也无法在没有 DEK 和 KEK 的情况下访问密钥。 +- **最小化暴露**：只有在绝对必要时才会解密密钥，从而降低意外泄露的风险，并符合处理敏感数据的最佳实践。 + +这种分层加密模型为用户最敏感的凭证和令牌 (Tokens) 提供了强有力的保护，同时在需要时仍能安全访问。 + +## 密钥类型 \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +目前，联合令牌集 (Federated token set) 是唯一开箱即用支持的密钥类型。不过，密钥保险库 (Secret Vault) 设计上可以适配任何类型的敏感信息。如果你需要支持其他类型的密钥，请[联系我们](https://logto.io/contact)——我们很乐意为你提供帮助。 +::: diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..dca239e11cd --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: 联邦令牌集 (Federated token set) +sidebar_label: 联邦令牌集 (Federated token set) +--- + +import Availability from '@components/Availability'; + + + +联邦令牌集 (Federated token set) 是存储在 Logto Secret Vault 中的一种密钥类型，用于安全管理由联邦第三方身份提供商颁发的访问令牌 (Access token) 和刷新令牌 (Refresh token)。当用户通过社交或企业单点登录 (SSO) 连接器进行认证 (Authentication) 时，Logto 会将颁发的令牌存储在 Vault 中。这些令牌随后可以被检索，用于代表用户访问第三方 API，无需重新认证 (Authentication)。 + +## 启用联邦令牌存储 \{#enable-federated-token-storage} + +### 社交连接器 \{#social-connectors} + +:::Info +此功能仅适用于支持令牌存储的连接器。目前支持的连接器包括：[GitHub](/integrations/github)、[Google](/integrations/google)、[Facebook](/integrations/facebook)、[标准 OAuth 2.0](/integrations/oauth2) 和 [标准 OIDC](/integrations/oidc)。更多连接器的支持将逐步推出。 +::: + +1. 前往 控制台 > 连接器 > 社交连接器。 +2. 选择你想要启用联邦令牌存储的社交连接器。 +3. 在“设置”页面，启用 **为持久 API 访问存储令牌** 选项。 + +### 企业单点登录 (SSO) 连接器 \{#enterprise-sso-connectors} + +:::Info +所有 OIDC 企业连接器均支持令牌存储。 +::: + +1. 前往 控制台 > 企业单点登录 (SSO)。 +2. 选择你想要启用联邦令牌存储的企业单点登录 (SSO) 连接器。 +3. 在“SSO 体验”标签页，启用 **为持久 API 访问存储令牌** 选项。 + +请确保保存你的更改。 + +## 令牌存储 \{#token-storage} + +启用联邦令牌存储后，每当用户通过社交或企业单点登录 (SSO) 连接器认证 (Authentication) 时，Logto 会自动存储由联邦身份提供商颁发的访问令牌 (Access token) 和刷新令牌 (Refresh token)。包括以下场景： + +- [社交登录与注册](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [企业单点登录 (SSO) 登录与注册](/end-user-flows/enterprise-sso) +- [通过 Account API 进行社交账号绑定](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +存储的令牌会附加到用户的社交或企业单点登录 (SSO) 身份上，使其能够在无需重新认证 (Authentication) 的情况下，后续检索令牌以访问 API。 + +### 检查令牌存储状态 \{#checking-token-storage-status} + +你可以在 Logto 控制台中检查用户的联邦令牌存储状态： + +1. 前往 控制台 > 用户。 +2. 点击你想要查看的用户，进入用户详情页。 +3. 滚动到 **连接** 区域。这里会列出该用户关联的所有社交和企业单点登录 (SSO) 连接。 +4. 每个连接条目会显示一个令牌状态标签，指示该连接是否已存储令牌。 +5. 点击连接条目可查看更多详情，包括已存储的访问令牌 (Access token) 元数据和刷新令牌 (Refresh token) 可用性（如有）。 + +你也可以通过 Management API 检查用户第三方身份及令牌存储状态： + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`：通过指定连接器 target（如 `github`、`google` 等）获取用户的社交身份及其令牌存储状态。 +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`：通过指定 SSO 连接器 ID 获取用户的企业单点登录 (SSO) 身份及其令牌存储状态。 + +### 令牌存储状态 \{#token-storage-status} + +- **Active（活跃）**：访问令牌 (Access token) 已存储且处于活跃状态。 +- **Expired（已过期）**：访问令牌 (Access token) 已存储但已过期。如果有刷新令牌 (Refresh token)，可用于获取新的访问令牌 (Access token)。 +- **Inactive（未激活）**：该连接未存储访问令牌 (Access token)。可能是用户未通过该连接认证 (Authentication) 或令牌存储已被删除。 +- **Not applicable（不适用）**：该连接器不支持令牌存储。 + +### 令牌元数据 \{#token-metadata} + +为保证数据完整性和安全性，所有令牌在存储到 Secret Vault 前都会被加密。实际令牌值仅对拥有适当授权的终端用户可见。开发者只能获取令牌集元数据，以了解存储令牌的状态，而不会暴露敏感内容。 + +- `createdAt`：首次建立连接并将令牌集存储到 Secret Vault 的时间戳。 +- `updatedAt`：令牌集最后一次被更新的时间。 + - 如果没有刷新令牌 (Refresh token)，该值与 **createdAt** 相同。 + - 如果有刷新令牌 (Refresh token)，该值反映最近一次访问令牌 (Access token) 被刷新时的时间。 +- `hasRefreshToken`：指示是否有刷新令牌 (Refresh token) 可用。 + 如果连接器支持离线访问且授权请求配置正确，Logto 会在身份提供商颁发时与访问令牌 (Access token) 一同存储刷新令牌 (Refresh token)。 + 当访问令牌 (Access token) 过期且存在有效的刷新令牌 (Refresh token) 时，用户请求访问已连接的提供商时，Logto 会自动尝试使用存储的刷新令牌 (Refresh token) 获取新的访问令牌 (Access token)。 +- `expiresAt`：访问令牌 (Access token) 的预计过期时间（单位：秒）。 + 该值基于身份提供商的 token endpoint 返回的 `expires_in` 计算得出。（仅当提供商在令牌响应中包含 `expires_in` 字段时可用。） +- `scope`：访问令牌 (Access token) 的权限范围，指示身份提供商授予的权限。 + 这有助于了解存储的访问令牌 (Access token) 可执行哪些操作。（仅当提供商在令牌响应中包含 `scope` 字段时可用。） +- `tokenType`：访问令牌 (Access token) 的类型，通常为 "Bearer"。 + （仅当提供商在令牌响应中包含 `token_type` 字段时可用。） + +## 令牌检索 \{#token-retrieval} + +启用令牌存储并将令牌安全存储在 Logto Secret Vault 后，终端用户可以通过集成 Logto 的 [User Account API](/end-user-flows/account-settings/by-account-api) 从你的客户端应用检索他们的第三方访问令牌 (Access token)。 + +- `GET /my-account/identities/:target/access-token`：通过指定连接器 target（如 github、google）获取社交身份的访问令牌 (Access token)。 + +- `GET /my-account/sso-identities/:connectorId/access-token`：通过指定连接器 ID 获取企业单点登录 (SSO) 身份的访问令牌 (Access token)。 + +:::info +了解如何[启用](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api)和[访问](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) Account API，并使用 Logto 颁发的访问令牌 (Access token)。 +::: + +### 令牌轮换 \{#token-rotation} + +令牌检索接口返回： + +- `200` OK：成功检索到访问令牌 (Access token) 且仍然有效。 +- `404` Not Found：用户没有与指定 target 或连接器 ID 关联的社交或企业单点登录 (SSO) 身份，或未存储访问令牌 (Access token)。 +- `401` Unauthorized：访问令牌 (Access token) 已过期。 + +如果访问令牌 (Access token) 已过期且有刷新令牌 (Refresh token)，Logto 会自动尝试刷新访问令牌 (Access token)，并在响应中返回新的访问令牌 (Access token)。Secret Vault 中的令牌存储也会同步更新为新的访问令牌 (Access token) 及其元数据。 + +## 令牌存储删除 \{#token-storage-deletion} + +联邦令牌存储与每个用户的社交或企业单点登录 (SSO) 连接直接关联。这意味着在以下情况下，存储的令牌集会被自动删除： + +- 关联的社交或企业单点登录 (SSO) 身份从用户账户中移除。 +- 用户账户从你的租户中被删除。 +- 社交或企业单点登录 (SSO) 连接器从你的租户中被删除。 + +### 撤销令牌 \{#revoking-tokens} + +你也可以手动删除用户的第三方令牌集以撤销访问权限： + +- 通过控制台： + 前往用户身份详情页，滚动到 **访问令牌 (Access token)** 区域（如有令牌存储），点击该区域末尾的 **删除令牌** 按钮。 +- 通过 Management API： + - `DELETE /api/secret/:id`：通过密钥 ID 删除指定密钥，该 ID 可在用户身份详情中获取。 + +撤销令牌集会强制用户在再次访问第三方 API 前，需重新通过第三方提供商认证 (Authentication) 以获取新的访问令牌 (Access token)。 + +## 重新认证 (Reauthentication) 与令牌续期 \{#reauthentication-and-token-renewal} + +在存储的访问令牌 (Access token) 已过期或应用需要请求额外 API 权限范围的场景下，终端用户可以通过第三方提供商重新认证 (Authentication) 以获取新的访问令牌 (Access token)——无需再次登录 Logto。 +这可以通过 Logto 的 [Social Verification API](https://openapi.logto.io/operation/operation-createverificationbysocial) 实现，允许用户重新发起联邦社交授权 (Authorization) 流程并更新其存储的令牌集。 + +:::note +重新发起联邦授权 (Authorization) 目前仅限于社交连接器。 +对于企业单点登录 (SSO) 连接器，重新认证 (Authentication) 和令牌续期需要用户重新发起完整的 Logto 认证 (Authentication) 流程，因为目前在登录后不支持直接与企业单点登录 (SSO) 提供商重新授权 (Authorization)。 +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as 用户 + participant Logto as Logto + participant Provider as 第三方提供商 + + User->>Logto: post /api/verification/social + Logto->>User: 跳转到第三方提供商 + User->>Provider: 认证 (Authentication) 并授权 (Authorization) + Provider->>User: 跳转回并携带授权码 + User->>Logto: post /api/verification/social/verify 携带授权码 + Logto->>User: 返回社交验证 ID + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. 用户通过调用 `POST /api/verification/social` 接口发起社交验证请求。用户可以指定自定义权限范围 (scope) 以请求第三方提供商的额外权限。 + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**：Logto 颁发的用户访问令牌 (Access token)。 + - **connectorId**：Logto 中的社交连接器 ID。 + - **redirectUri**：认证 (Authentication) 完成后将用户重定向回你应用的 URI。你需要在提供商的应用设置中注册该 URI。 + - **scope**：（可选）自定义权限范围 (scope)，用于请求第三方提供商的额外权限。如未指定，则使用连接器中配置的默认权限范围 (scope)。 + +2. Logto 创建新的社交验证记录，并返回社交验证 ID 及授权 (Authorization) URL，用于将用户重定向到第三方提供商进行认证 (Authentication)。 + + 响应示例： + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. 将用户重定向到授权 (Authorization) URL。用户在第三方提供商处进行认证 (Authentication) 并授权 (Authorization)。 + +4. 第三方提供商将用户重定向回你的客户端应用，并携带授权码。 + +5. 处理授权回调，将授权码转发到 Logto 的验证接口： + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**：Logto 颁发的用户访问令牌 (Access token)。 + - **verificationRecordId**：上一步返回的社交验证 ID。 + - **connectorData**：授权码及第三方提供商在回调时返回的其他数据。 + + :::note + 不要忘记校验 `state` 参数，以防止 CSRF 攻击。 + ::: + +6. Logto 验证授权码，并向第三方提供商换取新的访问令牌 (Access token) 和刷新令牌 (Refresh token)，然后在响应中返回社交验证 ID。 + +7. 最后，通过调用 `PATCH /my-account/identities/:target/access-token` 接口并携带社交验证 ID，更新用户的令牌存储： + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**：Logto 颁发的用户访问令牌 (Access token)。 + - **socialVerificationId**：上一步返回的已验证社交验证记录 ID。 + + 这将用新的访问令牌 (Access token) 和刷新令牌 (Refresh token) 更新 Logto Secret Vault 中的用户令牌集存储，使用户无需再次登录 Logto 即可访问第三方 API。 + + 更新后的访问令牌 (Access token) 将被返回。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 26cddcf8b02..0e755a449bd 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -4,7 +4,7 @@ sidebar_position: 4 # 个人访问令牌 (Personal access token) -个人访问令牌 (PATs) 为用户提供了一种安全的方式来授予[访问令牌 (Access token)](https://auth.wiki/access-token)，而无需使用他们的凭据和交互式登录。这对于 CI / CD、脚本或需要以编程方式访问资源的应用程序非常有用。 +个人访问令牌 (PATs) 为用户提供了一种安全的方式来授予[访问令牌 (Access token)](https://auth.wiki/access-token)，而无需使用他们的凭据和交互式登录。这对于 CI/CD、脚本或需要以编程方式访问资源的应用程序非常有用。 ## 管理个人访问令牌 \{#managing-personal-access-tokens} @@ -20,24 +20,36 @@ sidebar_position: 4 创建 PAT 后，你可以通过令牌交换端点将其用于为你的应用程序授予访问令牌 (Access tokens)。 +:::tip 令牌流等价性 + +使用 PAT 获取的访问令牌 (Access tokens) 与通过标准 `refresh_token` 流获取的令牌**完全相同**。这意味着： + +- **组织 (Organization) 上下文**：通过 PAT 获取的令牌支持与 refresh token 流相同的组织权限和权限 (Scopes) +- **授权 (Authorization) 流程**：你可以将 PAT 交换得到的访问令牌 (Access tokens) 用于[组织权限](/authorization/organization-permissions)和[组织级 API 资源](/authorization/organization-level-api-resources) +- **令牌验证**：验证逻辑相同——只有初始授权类型不同 + +如果你在与组织 (Organizations) 相关的场景中工作，无论使用 PAT 还是 refresh token，访问模式和权限都是一样的。 + +::: + ### 请求 \{#request} -应用程序使用 HTTP POST 方法，向租户的 [令牌端点](/integrate-logto/application-data-structure#token-endpoint) 发起一次带有特殊授权类型的[令牌交换请求](https://auth.wiki/authorization-code-flow#token-exchange-request)。以下参数以 `application/x-www-form-urlencoded` 格式包含在 HTTP 请求实体主体中。 +应用程序使用 HTTP POST 方法，向租户的 [token endpoint](/integrate-logto/application-data-structure#token-endpoint) 发起[令牌交换请求](https://auth.wiki/authorization-code-flow#token-exchange-request)，并使用特殊的授权类型。以下参数以 `application/x-www-form-urlencoded` 格式包含在 HTTP 请求实体中。 1. `client_id`：必填。应用程序的 client ID。 2. `grant_type`：必填。该参数的值必须为 `urn:ietf:params:oauth:grant-type:token-exchange`，表示正在执行令牌交换。 -3. `resource`：可选。资源指示器 (Resource indicator)，与其他令牌请求相同。 +3. `resource`：可选。资源指示器，与其他令牌请求相同。 4. `scope`：可选。请求的权限 (Scopes)，与其他令牌请求相同。 5. `subject_token`：必填。用户的 PAT。 6. `subject_token_type`：必填。`subject_token` 参数中提供的安全令牌类型。该参数的值必须为 `urn:logto:token-type:personal_access_token`。 ### 响应 \{#response} -如果令牌交换请求成功，租户的令牌端点会返回一个代表用户身份的访问令牌 (Access token)。响应以 `application/json` 格式在 HTTP 响应实体主体中包含以下参数。 +如果令牌交换请求成功，租户的 token endpoint 会返回一个代表用户身份的访问令牌 (Access token)。响应以 `application/json` 格式在 HTTP 响应实体中包含以下参数。 1. `access_token`：必填。用户的访问令牌 (Access token)，与 `authorization_code` 或 `refresh_token` 等其他令牌请求相同。 2. `issued_token_type`：必填。签发令牌的类型。该参数的值必须为 `urn:ietf:params:oauth:token-type:access_token`。 -3. `token_type`：必填。令牌的类型。该参数的值必须为 `Bearer`。 +3. `token_type`：必填。令牌类型。该参数的值必须为 `Bearer`。 4. `expires_in`：必填。访问令牌 (Access token) 的有效期（秒）。 5. `scope`：可选。访问令牌 (Access token) 的权限 (Scopes)。 @@ -85,10 +97,10 @@ Content-Type: application/json ## 相关资源 \{#related-resources} - 什么是个人访问令牌 (Personal access token)？什么时候应该使用个人访问令牌 (Personal access token)？ + 什么是个人访问令牌 (Personal access token)？什么时候应该使用个人访问令牌？ - 个人访问令牌 (Personal access token)、机器对机器 (Machine-to-Machine) 认证 (Authentication) 和 API - 密钥的定义及其实际场景 + 个人访问令牌 (Personal Access Tokens)、机器对机器 (Machine-to-Machine) 认证 (Authentication) 和 + API Keys 的定义及其实际应用场景 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index f95fa332bde..b53c92b704f 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -4,23 +4,25 @@ sidebar_position: 5 # 用户迁移 -Logto 支持将现有用户从其他平台手动迁移，本文将向你展示如何通过 Management API 导入现有用户，并介绍迁移前你需要考虑的事项。 +Logto 支持将现有用户从其他平台手动迁移，本指南将向你展示如何通过 Management API 导入现有用户，并介绍在迁移前你需要考虑的事项。 ## 用户 schema \{#user-schema} -在开始之前，让我们先看一下 Logto 中的 [用户 schema](/user-management/user-data/#user-profile)。你需要关注用户 schema 的三个部分： +在开始之前，让我们先了解一下 Logto 中的 [用户 schema](/user-management/user-data/#user-profile)。用户 schema 有 3 个部分需要你注意： -1. **基础数据**：来自用户资料的基本信息，你可以将现有用户资料中的数据映射到这里。 -2. **自定义数据**：用于存储额外的用户信息，你可以用它来存储无法匹配基础数据的字段。 +1. **基础数据**：来自用户资料的基本信息，你可以将现有用户资料中的数据与其对应。 +2. **自定义数据**：用于存储额外的用户信息，你可以用它来存储无法匹配基础数据的内容。 3. **社交身份**：存储通过社交登录获取的用户信息。 你可以创建一个映射，将现有用户资料中的信息对应到 **基础数据** 和 **自定义数据**。对于社交登录，你需要额外的步骤来导入社交身份，请参考 [关联社交身份到用户](https://openapi.logto.io/operation/operation-createuseridentity) 的 API。 ## 密码哈希 \{#password-hashing} -Logto 使用 [Argon2](https://en.wikipedia.org/wiki/Argon2) 对用户密码进行哈希，同时也支持 `MD5`、`SHA1`、`SHA256` 和 `Bcrypt` 等其他算法，方便迁移。这些算法被认为是不安全的，相应的密码哈希将在用户首次成功登录时迁移到 Argon2。 +Logto 使用 [Argon2](https://en.wikipedia.org/wiki/Argon2) 对用户密码进行哈希，同时也支持 `MD5`、`SHA1`、`SHA256` 和 `Bcrypt` 等其他算法，方便迁移。这些算法被认为是不安全的，相应的密码哈希将在用户首次成功登录时迁移为 Argon2。 -如果你使用了其他哈希算法或加盐方式，可以将 `passwordAlgorithm` 设置为 `Legacy`，这样你就可以使用 Node.js 支持的任意哈希算法。你可以在 [Node.js crypto 文档](https://nodejs.org/api/crypto.html#cryptogethashes) 中找到支持的算法列表。在这种情况下，`passwordDigest` 应为包含哈希算法及其他算法参数的 JSON 字符串。 +如果你使用了其他哈希算法或加盐方式，可以将 `passwordAlgorithm` 设置为 `Legacy`，这样你可以使用 Node.js 支持的任何哈希算法。支持的算法列表可在 [Node.js crypto 文档](https://nodejs.org/api/crypto.html#cryptogethashes) 中找到。在这种情况下，`passwordDigest` 将是一个包含哈希算法及其他算法参数的 JSON 字符串。 + +### 通用 Legacy 格式 \{#general-legacy-format} JSON 字符串的格式如下： @@ -28,9 +30,9 @@ JSON 字符串的格式如下： ["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"] ``` -你可以在参数中用 `@` 作为实际密码值的占位符。 +你可以用 `@` 作为参数中实际密码值的占位符。 -例如，如果你使用 SHA256 并加盐，可以按如下格式存储密码： +例如，如果你使用 SHA256 加盐，可以按如下格式存储密码： ```json ["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"] @@ -44,10 +46,40 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### PBKDF2 支持 \{#pbkdf2-support} + +Logto 特别支持 [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2)。 + +要迁移使用 PBKDF2 哈希的密码，将 `passwordAlgorithm` 设置为 `Legacy`，并将 `passwordDigest` 格式化如下： + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +参数说明： + +- **`salt`**：原始哈希中使用的盐值 +- **`iterations`**：迭代次数（如 `"1000"`） +- **`keylen`**：派生密钥的字节长度（如 `"20"`） +- **`digest`**：使用的哈希函数（如 `"sha512"`、`"sha256"`、`"sha1"`） +- **`@`**：实际密码值的占位符 +- **`expected_hashed_value`**：期望的哈希结果（十六进制字符串） + +**迁移示例 payload：** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## 迁移步骤 \{#steps-to-migrate} 1. **准备用户数据** - 你应先从现有平台导出用户数据，然后将用户信息映射到 Logto 用户 schema。我们建议你将映射后的数据整理为 JSON 格式。以下是用户数据的示例： + 你应先从现有平台导出用户数据，然后将用户信息映射到 Logto 用户 schema。建议你将映射后的数据整理为 JSON 格式。以下是用户数据的示例： ```json [ @@ -69,7 +101,7 @@ const expectedHashedValue = hash.digest('hex'); 3. **配置 Management API 连接** 我们将使用 Management API 导入用户数据，你可以参考 [Management API](/integrate-logto/interact-with-management-api) 了解如何在开发环境中配置连接。 4. **导入用户数据** - 建议你编写脚本逐个导入用户数据，我们将调用 [create user](https://openapi.logto.io/operation/operation-createuser) API 导入用户数据。以下是脚本示例： + 建议你编写脚本逐个导入用户数据，我们将调用 [create user](https://openapi.logto.io/operation/operation-createuser) API 来导入用户数据。以下是脚本示例： ```jsx const users = require('./users.json'); @@ -85,7 +117,7 @@ const expectedHashedValue = hash.digest('hex'); }, body: JSON.stringify(user), }); - // 为避免触发限流，适当休眠 + // 为避免触发速率限制，适当延时 await new Promise((resolve) => setTimeout(resolve, 200)); } catch (error) { console.error(`Failed to import user ${user.username}: ${error.message}`); @@ -96,7 +128,7 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -请注意该 API 接口有速率限制，你应在每次请求之间添加休眠以避免触发限流。详情请查看我们的 [速率限制](/integrate-logto/interact-with-management-api/#rate-limit) 页面。 +请注意，API 接口有速率限制，你应在每次请求之间添加延时以避免触发速率限制。详情请查看我们的 [速率限制](/integrate-logto/interact-with-management-api/#rate-limit) 页面。 如果你有大量用户数据（10 万以上），可以[联系我们](https://logto.io/contact)以提升速率限制。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md b/i18n/zh-TW/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md index 5dada72640e..e1b0ad80b5a 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/concepts/core-service/configuration.md @@ -1,67 +1,68 @@ -# 配置 +# 設定 ## 環境變數 {#environment-variables} -### 使用方法 {#usage} +### 用法 {#usage} Logto 依照以下順序處理環境變數： - 系統環境變數 -- 專案根目錄中的 `.env` 文件，符合 [dotenv](https://github.com/motdotla/dotenv#readme) 格式 +- 專案根目錄下的 `.env` 檔案，格式遵循 [dotenv](https://github.com/motdotla/dotenv#readme) 標準 -因此，系統環境變數將覆蓋 `.env` 中的值。 +因此，系統環境變數會覆蓋 `.env` 中的值。 ### 變數 {#variables} :::caution -如果你在專案根目錄中透過 `npm start` 運行 Logto，`NODE_ENV` 將始終為 `production`。 +如果你在專案根目錄下透過 `npm start` 執行 Logto，`NODE_ENV` 會永遠是 `production`。 ::: -在預設值中，`protocol` 將根據你的 HTTPS 配置為 `http` 或 `https`。 - -| Key | Default Value | Type | Description | -| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto 運行的環境類型。 | -| PORT | `3001` | `number` | Logto 監聽的本地端口。 | -| ADMIN_PORT | `3002` | `number` | Logto 管理控制台監聽的本地端口。 | -| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 設置為 `1` 或 `true` 以禁用管理控制台的端口。若未設置 `ADMIN_ENDPOINT`，將完全禁用管理控制台。 | -| DB_URL | N/A | `string` | Logto 資料庫的 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 | -| HTTPS_CERT_PATH | `undefined` | string | undefined | 詳情請參閱 [啟用 HTTPS](#enabling-https)。 | -| HTTPS_KEY_PATH | `undefined` | string | undefined | 同上。 | -| TRUST_PROXY_HEADER | `false` | `boolean` | 同上。 | -| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | 你可以為線上測試或生產環境指定自定義域名的 URL。這也會影響 [OIDC 簽發者識別符](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 | -| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 你可以為生產環境指定自定義域名的 URL（例如 `ADMIN_ENDPOINT=https://admin.domain.com`）。這也會影響管理控制台重定向 URI 的值。 | -| CASE_SENSITIVE_USERNAME | `true` | `boolean` | 指定使用者名稱是否區分大小寫。修改此值時請謹慎；更改不會自動調整現有資料庫數據，需要手動管理。 | +在預設值中，`protocol` 會根據你的 HTTPS 設定為 `http` 或 `https`。 + +| Key | 預設值 | 類型 | 說明 | +| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | Logto 執行時所處的環境類型。 | +| PORT | `3001` | `number` | Logto 監聽的本地埠號。 | +| ADMIN_PORT | `3002` | `number` | Logto 管理主控台監聽的本地埠號。 | +| ADMIN_DISABLE_LOCALHOST | N/A | string | boolean | number | 設為 `1` 或 `true` 可停用管理主控台的埠號。若未設定 `ADMIN_ENDPOINT`，將完全停用管理主控台。 | +| DB_URL | N/A | `string` | Logto 資料庫的 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 | +| HTTPS_CERT_PATH | `undefined` | string | undefined | 詳情請參閱 [啟用 HTTPS](#enabling-https)。 | +| HTTPS_KEY_PATH | `undefined` | string | undefined | 同上。 | +| TRUST_PROXY_HEADER | `false` | `boolean` | 同上。 | +| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | 你可以指定自訂網域的 URL 以進行線上測試或正式環境。這也會影響 [OIDC 簽發者識別碼 (issuer identifier)](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 | +| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | 你可以指定正式環境下自訂網域的 URL（例如：`ADMIN_ENDPOINT=https://admin.domain.com`）。這也會影響管理主控台重新導向 URI 的值。 | +| CASE_SENSITIVE_USERNAME | `true` | `boolean` | 指定使用者名稱是否區分大小寫。修改此值時請謹慎；變更不會自動調整現有資料庫資料，需手動管理。 | +| SECRET_VAULT_KEK | `undefined` | `string` | 用於加密 [Secret Vault](/secret-vault) 中資料加密金鑰（DEK, Data Encryption Keys）的金鑰加密金鑰（KEK, Key Encryption Key）。Secret Vault 正常運作必須設定。必須為 base64 編碼字串。建議使用 AES-256（32 bytes）。範例：`crypto.randomBytes(32).toString('base64')` | ### 啟用 HTTPS {#enabling-https} #### 使用 Node {#using-node} -Node 原生支持 HTTPS。提供 **BOTH** `HTTPS_CERT_PATH` 和 `HTTPS_KEY_PATH` 以通過 Node 啟用 HTTPS。 +Node 原生支援 HTTPS。提供 **BOTH** `HTTPS_CERT_PATH` 與 `HTTPS_KEY_PATH` 即可透過 Node 啟用 HTTPS。 -`HTTPS_CERT_PATH` 表示你的 HTTPS 證書路徑，而 `HTTPS_KEY_PATH` 表示你的 HTTPS 金鑰路徑。 +`HTTPS_CERT_PATH` 指向你的 HTTPS 憑證路徑，`HTTPS_KEY_PATH` 則指向你的 HTTPS 金鑰路徑。 -#### 使用 HTTPS 代理 {#using-a-https-proxy} +#### 使用 HTTPS 代理伺服器 {#using-a-https-proxy} -另一種常見做法是在 Node 前面設置一個 HTTPS 代理（例如 Nginx）。 +另一常見做法是在 Node 前方設置 HTTPS 代理伺服器（如 Nginx）。 -在這種情況下，你可能需要將 `TRUST_PROXY_HEADER` 設置為 `true`，以指示是否應信任代理標頭字段。Logto 將把該值傳遞給 [Koa 應用程式設置](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings)。 +此時，建議將 `TRUST_PROXY_HEADER` 設為 `true`，表示信任代理伺服器的標頭欄位。Logto 會將此值傳遞給 [Koa 應用程式設定](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings)。 -請參閱 [信任 TLS 卸載代理](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) 以了解何時配置此字段。 +何時需要設定此欄位，請參閱 [信任 TLS 卸載代理伺服器](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies)。 -## 資料庫配置 {#database-configs} +## 資料庫設定 {#database-configs} -管理過多的環境變數既不高效也不靈活，因此我們的大多數一般配置都存儲在資料庫表 `logto_configs` 中。 +管理過多環境變數既沒效率又不夠彈性，因此我們將大多數通用設定存放於資料庫表格 `logto_configs`。 -該表是一個簡單的鍵值存儲，鍵可枚舉如下： +該表格為簡單的鍵值儲存，key 可列舉如下： -| Key | Type | Description | -| ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------- | -| oidc.cookieKeys | string[] | [簽名 Cookie 鍵](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys) 的字串數組。 | -| oidc.privateKeys | string[] | 用於 [OIDC JWT 簽名](https://openid.net/specs/openid-connect-core-1_0.html#Signing) 的私鑰內容字串數組。 | +| Key | 類型 | 說明 | +| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------- | +| oidc.cookieKeys | string[] | [簽署 cookie 金鑰](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#cookieskeys) 的字串陣列。 | +| oidc.privateKeys | string[] | [OIDC JWT 簽署](https://openid.net/specs/openid-connect-core-1_0.html#Signing) 用私鑰內容的字串陣列。 | ### 支援的私鑰類型 {#supported-private-key-types} -- EC (P-256, secp256k1, P-384, 和 P-521 曲線) +- EC（P-256、secp256k1、P-384、P-521 曲線） - RSA -- OKP (Ed25519, Ed448, X25519, X448 子類型) +- OKP（Ed25519、Ed448、X25519、X448 子類型） diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx index 4207afd1479..28e4821ee1c 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/enterprise-connectors.mdx @@ -13,11 +13,11 @@ import Saml from '@site/docs/connectors/assets/icons/sso-saml.svg'; Logto 的 [單一登入 (SSO, Single Sign-On) 解決方案](/end-user-flows/enterprise-sso) 簡化了企業客戶的存取管理。企業 SSO 連接器對於為不同企業客戶啟用 SSO 至關重要。 -這些連接器促進你的服務與企業身分提供者 (IdP) 之間的驗證流程。Logto 支援 [SP 發起 SSO](/end-user-flows/enterprise-sso/sp-initiated-sso) 及 [IdP 發起 SSO](/end-user-flows/enterprise-sso/idp-initiated-sso)，讓組織成員能使用現有公司帳號存取你的服務，提升安全性與生產力。 +這些連接器協助你的服務與企業身分提供者 (IdP) 之間的驗證 (Authentication) 流程。Logto 支援 [SP 發起 SSO](/end-user-flows/enterprise-sso/sp-initiated-sso) 及 [IdP 發起 SSO](/end-user-flows/enterprise-sso/idp-initiated-sso)，讓組織成員可使用現有公司帳號存取你的服務，提升安全性與生產力。 ## 企業連接器 (Enterprise connectors) \{#enterprise-connectors} -Logto 提供多種主流企業身分提供者的預建連接器，方便快速整合。如有自訂需求，也支援透過 [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) 與 [SAML](https://auth.wiki/saml) 協議進行整合。 +Logto 提供多種主流企業身分提供者的預建連接器，方便快速整合。如有自訂需求，也支援透過 [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) 與 [SAML](https://auth.wiki/saml) 協定進行整合。 ### 主流企業連接器 (Popular enterprise connectors) \{#popular-enterprise-connectors} @@ -81,7 +81,7 @@ Logto 提供多種主流企業身分提供者的預建連接器，方便快速 ]} /> -如果我們的標準連接器無法滿足你的特殊需求，歡迎隨時聯繫我們。 +如果標準連接器無法滿足你的特殊需求，歡迎隨時聯絡我們。 ## 設定企業連接器 (Configuring enterprise connectors) \{#configuring-enterprise-connectors} @@ -90,21 +90,22 @@ Logto 提供多種主流企業身分提供者的預建連接器，方便快速 3. 輸入唯一名稱（例如：Acme 公司用 Okta）。 4. 在「連線」分頁設定與你的 IdP 的連線。各連接器設定請參考上方指南。 5. 在「使用體驗 (Experience)」分頁自訂 SSO 體驗與**電子郵件網域**。 -6. 對於 SAML 企業連接器，可選擇性在「IdP 發起 SSO」分頁啟用 IdP 發起 SSO。[詳情請參考指南](/end-user-flows/enterprise-sso/idp-initiated-sso)。 +6. SAML 企業連接器可選擇於「IdP 發起 SSO」分頁啟用 IdP 發起 SSO。詳情請參考[相關指南](/end-user-flows/enterprise-sso/idp-initiated-sso)。 7. 儲存變更。 請注意以下設定： -- **電子郵件網域 (Email domains)**：若使用者輸入的電子郵件網域在某個企業 SSO 連接器的「企業電子郵件網域」欄位中，該使用者將被導向該 SSO 連接器對應的登入網址。 +- **電子郵件網域 (Email domains)**：若使用者輸入的電子郵件網域在某個企業 SSO 連接器的「企業電子郵件網域」欄位中，則會自動導向該 SSO 連接器的登入網址。 :::note - 請特別注意，當你在 SSO 連接器中設定相關電子郵件網域後，屬於這些網域的使用者將被強制使用 [SSO 登入](/end-user-flows/enterprise-sso)。 + 請特別注意，當你在 SSO 連接器中設定相關電子郵件網域後，這些網域的使用者將被強制使用 [SSO 登入](/end-user-flows/enterprise-sso)。 - 換句話說，只有未在 SSO 連接器中設定的網域郵件，才能使用「電子郵件 + 驗證碼」或「電子郵件 + 密碼」登入（前提是這兩種登入方式已在登入體驗中啟用）。 + 換句話說，只有未在 SSO 連接器設定的網域，才能使用「電子郵件 + 驗證碼」或「電子郵件 + 密碼」登入（前提是這兩種登入方式已在登入體驗中啟用）。 ::: -- **同步使用者資料 (Sync user profiles)**：選擇何時同步使用者資料（如頭像、名稱）。預設為「僅首次登入時同步」。你也可以選擇「每次登入時皆同步」，但可能導致自訂使用者資料被覆蓋。 -- **顯示資訊 (Display information)**：可選擇自訂連接器的顯示名稱與 Logo。當多個連接器綁定同一電子郵件網域時非常實用。使用者會在被導向 IdP 登入頁前，從 SSO 連接器按鈕列表中選擇所需的 IdP。 +- **同步使用者資料 (Sync user profiles)**：選擇何時同步使用者資料（如頭像、名稱）。預設為「僅首次登入時同步」。你也可以選擇「每次登入時皆同步」，但可能導致自訂資料被覆蓋。 +- **啟用權杖儲存 (Enable token storage)**：對於 OIDC 企業連接器，你可以啟用權杖儲存，讓 Logto 在使用者以企業 IdP 登入時，安全儲存存取權杖 (Access token) 與重新整理權杖 (Refresh token) 於 [秘密保管庫 (Secret Vault)](/secret-vault)。這讓你的應用程式能以使用者身分存取第三方 API，而無需再次驗證。詳見 [聯邦權杖儲存 (Federated token storage)](/secret-vault/federated-token-set)。 +- **顯示資訊 (Display information)**：可自訂連接器的顯示名稱與 Logo。當多個連接器綁定同一電子郵件網域時，這功能特別實用。使用者會在 SSO 連接器按鈕列表中選擇欲登入的 IdP，再被導向 IdP 登入頁。 ## 啟用企業 SSO (Enabling enterprise SSO) \{#enabling-enterprise-sso} @@ -112,11 +113,11 @@ Logto 提供多種主流企業身分提供者的預建連接器，方便快速 2. 啟用「企業 SSO」開關。 3. 儲存變更。 -啟用後，你的登入頁將出現「單一登入 (Single Sign-On)」按鈕。擁有啟用 SSO 電子郵件網域的企業使用者可透過其企業身分提供者 (IdP) 存取你的服務。想了解更多 SSO 使用者體驗，請參閱使用者流程：[企業 SSO](/end-user-flows/enterprise-sso)。 +啟用後，你的登入頁將出現「單一登入 (Single Sign-On)」按鈕。擁有 SSO 啟用網域的企業使用者可透過其企業身分提供者 (IdP) 存取你的服務。更多 SSO 使用者體驗，請參閱使用者流程：[企業 SSO](/end-user-flows/enterprise-sso)。 ## 即時佈建至組織 (Just-in-time to organization) \{#just-in-time-to-organization} -在 Logto 中，[即時佈建 (JIT, Just-in-Time provisioning)](https://auth.wiki/jit-provisioning) 是一種在使用者首次登入系統時，自動分配組織成員資格與角色的流程。 +在 Logto，[即時佈建 (JIT, Just-in-Time provisioning)](https://auth.wiki/jit-provisioning) 是一種在使用者首次登入系統時，自動分配組織成員資格與角色的流程。 Logto 提供在組織內設定 SSO 連接器 JIT 佈建的入口，詳見[參考說明](/organizations/just-in-time-provisioning)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/social.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/social.mdx index 9e840214712..f77b329ff3a 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/social.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/connectors/social.mdx @@ -1,21 +1,21 @@ --- id: social-connectors -title: 社交連接器 -sidebar_label: 社交連接器 +title: 社交連接器 (Social connectors) +sidebar_label: 社交連接器 (Social connectors) sidebar_position: 3 --- -# 社交連接器 +# 社交連接器 (Social connectors) -透過 Logto 啟用[社交登入](/end-user-flows/sign-up-and-sign-in/social-sign-in)，簡化使用者註冊流程並提高轉換率。使用者可以快速且安全地使用現有的社交媒體帳戶登入，無需創建密碼或進行複雜的註冊流程。Logto 提供多種預建的社交連接器，並支援自訂整合以達到最大的靈活性。 +透過在 Logto 啟用 [社交登入](/end-user-flows/sign-up-and-sign-in/social-sign-in)，簡化使用者註冊流程並提升轉換率。使用者可快速且安全地利用現有社群帳號登入，無需建立密碼或經歷繁瑣註冊流程。Logto 提供多種預建社交連接器，並支援自訂整合，靈活滿足各種需求。 ## 選擇你的社交連接器 \{#choose-your-social-connectors} Logto 提供兩種類型的社交連接器： -### 流行的社交連接器 \{#popular-social-connectors} +### 熱門社交連接器 \{#popular-social-connectors} -Logto 提供預配置的流行社交平台連接器，可立即使用。 +Logto 為主流社交平台提供預先配置的連接器，開箱即用。 ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -34,7 +34,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Google', href: '/integrations/google', - description: 'Google 連接器為你的應用程式提供使用 Google 的 OAuth 2.0 驗證系統的簡便方式。', + description: 'Google 連接器為你的應用程式提供簡潔的 Google OAuth 2.0 驗證 (Authentication) 系統整合方式。(The Google connector provides a succinct way for your application to use Google\'s OAuth 2.0 authentication system.)', customProps: { icon: , } @@ -43,7 +43,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Facebook', href: '/integrations/facebook', - description: 'Facebook 連接器允許你的應用程式使用 Facebook 的 OAuth 2.0 驗證系統。', + description: 'Facebook 連接器讓你的應用程式可使用 Facebook OAuth 2.0 驗證 (Authentication) 系統。(The Facebook connector allows your application to use Facebook\'s OAuth 2.0 authentication system.)', customProps: { icon: , } @@ -52,7 +52,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Apple', href: '/integrations/apple', - description: 'Logto 的 Apple 社交登入官方連接器。', + description: 'Logto 官方 Apple 社交登入連接器。(The official Logto connector for Apple social sign-in.)', customProps: { icon: , } @@ -61,7 +61,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Microsoft Azure AD', href: '/integrations/azuread', - description: 'Microsoft Azure AD 連接器為你的應用程式提供使用 Azure 的 OAuth 2.0 驗證系統的簡便方式。', + description: 'Microsoft Azure AD 連接器為你的應用程式提供簡潔的 Azure OAuth 2.0 驗證 (Authentication) 系統整合方式。(The Microsoft Azure AD connector provides a succinct way for your application to use Azure\'s OAuth 2.0 authentication system.)', customProps: { icon: , } @@ -70,7 +70,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'GitHub', href: '/integrations/github', - description: 'Logto 的 GitHub 社交登入官方連接器。', + description: 'Logto 官方 GitHub 社交登入連接器。(The official Logto connector for GitHub social sign-in.)', customProps: { icon: , } @@ -79,7 +79,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'Discord', href: '/integrations/discord', - description: 'Discord 連接器為你的應用程式提供使用 Discord 作為授權系統的方式。', + description: 'Discord 連接器讓你的應用程式可使用 Discord 作為授權 (Authorization) 系統。(The Discord connector provides a way for your application to use Discord as an authorization system.)', customProps: { icon: , } @@ -92,7 +92,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; ### 自訂你的社交連接器 \{#customize-your-social-connectors} -對於自訂需求，利用 OAuth 2.0 和 OIDC (OpenID Connect) 標準整合你偏好的提供者。 +如有自訂需求，可利用 OAuth 2.0 與 OIDC（OpenID Connect）標準整合你偏好的服務提供者。 ```mdx-code-block , } @@ -110,7 +110,7 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; type: 'link', label: 'OIDC', href: '/integrations/oidc', - description: 'Logto 的 OAuth 2.0 協議官方連接器。', + description: 'Logto 官方 OAuth 2.0 協議連接器。(The official Logto connector for OAuth 2.0 protocol.)', customProps: { icon: , } @@ -119,29 +119,30 @@ import OIDC from '@site/docs/connectors/assets/icons/oidc.svg'; /> ``` -如果我們的標準連接器無法滿足你的特定需求，請隨時[聯繫我們](https://logto.productlane.com/roadmap)。對於 Logto OSS 使用者，如果需求緊急，你可以[實作你的連接器 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector)。我們始終歡迎[貢獻](/logto-oss/contribution)；你的努力可能會幫助其他有相同需求的社群成員。 +若標準連接器無法滿足你的特殊需求，歡迎 [聯絡我們](https://logto.productlane.com/roadmap)。若你是 OSS 使用者，且需求急迫，也可自行 [實作你的連接器 (OSS)](/logto-oss/develop-your-connector/implement-connectors#build-a-social-connector)。我們也非常歡迎 [貢獻](/logto-oss/contribution)；你的努力可能幫助到其他有相同需求的社群成員。 -## 配置步驟 \{#configuration-steps} +## 設定步驟 \{#configuration-steps} 1. 前往 控制台 > 連接器 > 社交連接器。 -2. 點擊「新增社交連接器」並選擇所需類型。 -3. 按照 README 指南完成所需欄位並自訂設置。 -4. 點擊「儲存並完成」以完成。 -5. 通過啟動社交登入來測試連接器。 +2. 點擊「新增社交連接器」，選擇所需類型。 +3. 依照 README 指引，填寫必要欄位並自訂設定。 +4. 點擊「儲存並完成」。 +5. 測試連接器，啟動一次社交登入流程。 -請注意以下設置： +請注意以下設定： -- **身分提供者名稱 (Identity provider name)**：每個社交連接器都有一個唯一的身分提供者 (IdP) 名稱以區分使用者身分。常見連接器使用固定的 IdP 名稱，自訂連接器則需要唯一值。了解更多 [IdP 名稱](/connectors/connector-data-structure#target-identity-provider-name) 的詳細資訊。 -- **同步使用者資料**：選擇何時同步[使用者資料資訊](/user-management/user-data#social-identities)（例如頭像、使用者名稱）。預設為「僅在註冊時同步」。另一選擇是「每次登入時同步」，但可能會覆蓋自訂使用者資料。 +- **身分提供者名稱 (Identity provider name)**：每個社交連接器都有唯一的身分提供者 (IdP) 名稱，用於區分使用者身分。常見連接器使用固定 IdP 名稱，自訂連接器則需填寫唯一值。詳情請參閱 [IdP 名稱](/connectors/connector-data-structure#target-identity-provider-name)。 +- **同步使用者資料 (Sync user profiles)**：選擇何時同步 [使用者資料](/user-management/user-data#social-identities)（如頭像、用戶名）。預設為「僅註冊時同步」，也可選擇「每次登入時同步」，但可能覆蓋自訂資料。 +- **啟用權杖儲存 (Enable token storage)**：對於支援的社交連接器，你可啟用權杖儲存功能，當使用者以社交提供者登入時，將存取權杖 (Access token) 與重新整理權杖 (Refresh token) 安全儲存於 Logto 的 [秘密保管庫 (Secret Vault)](/secret-vault)。這讓你的應用程式可代表使用者存取第三方 API，無需重複驗證。詳情請參閱 [聯邦權杖儲存 (Federated token storage)](/secret-vault/federated-token-set)。 ## 啟用社交登入 \{#enable-social-sign-in} -成功創建社交連接器後，你可以在登入體驗中將其啟用為社交登入按鈕（例如，繼續使用 Google）。 +成功建立社交連接器後，你可在登入體驗中啟用社交登入按鈕（如「以 Google 繼續」）。 -1. 前往 控制台 > 登入體驗 > 註冊和登入。 -2. （可選）如果只需要社交登入，選擇「不適用」作為註冊識別符。 -3. 將配置好的社交連接器添加到「社交登入」部分。 -4. 根據需要重新排序連接器。 +1. 前往 控制台 > 登入體驗 > 註冊與登入。 +2. （選填）若僅需社交登入，註冊識別碼可選「不適用」。 +3. 將已設定的社交連接器加入「社交登入」區塊。 +4. 依需求調整連接器順序。 5. 點擊「儲存變更」並測試「即時預覽」。 -參閱[社交登入](/end-user-flows/sign-up-and-sign-in/social-sign-in)以了解詳細資訊。 +詳情請參閱 [社交登入](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx index 6ca8310563a..75c6c8eb714 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/facebook sidebar_label: Facebook sidebar_custom_props: - description: Facebook 是一個擁有數十億用戶的全球社交媒體平台。 + description: Facebook 是一個擁有數十億用戶的全球社群媒體平台。 tutorial_config_name: Facebook login --- @@ -12,18 +12,63 @@ import Integration from './_integration.mdx'; # 設定 Facebook 社交登入 -Logto 的官方 Facebook 社交登入連接器。 +整合 Facebook OAuth 2.0 驗證 (Authentication) 系統，啟用「以 Facebook 登入」、帳號連結，以及安全存取 Facebook API。 ## 開始使用 \{#get-started} -Facebook 連接器為你的應用程式提供了一種簡潔的方式來使用 Facebook 的 OAuth 2.0 驗證系統。 +Facebook 連接器 (Connector) 支援 OAuth 2.0 整合，讓你的應用程式可以： + +- 新增「以 Facebook 登入」驗證 (Authentication) +- 將使用者帳號與 Facebook 身分連結 +- 從 Facebook 同步使用者個人資料資訊 +- 透過 Logto Secret Vault 安全儲存權杖，存取 Facebook API 以自動化任務（例如：回覆討論串、在你的應用程式中發佈內容與影片） + +要設定這些驗證 (Authentication) 功能，請先在 Logto 建立 Facebook 連接器 (Connector)： + +1. 前往 [Logto > Connector > Social connector](https://cloud.logto.io/to/connectors/social)。 +2. 點擊 **新增社交連接器 (Add social connector)**，選擇 **Facebook**，點擊 **下一步 (Next)**，並依照分步教學完成整合。 -## 參考資料 \{#references} +## 運用 Facebook 連接器 (Connector) \{#utilize-the-facebook-connector} + +建立 Facebook 連接器 (Connector) 並與 Facebook 連結後，你可以將其整合進終端使用者流程。請依需求選擇下列選項： + +### 啟用「以 Facebook 登入」 \{#enable-sign-in-with-facebook} + +1. 在 Logto Console，前往 登入體驗 (Sign-in experience) > 註冊與登入 (Sign-up and sign-in) +2. 在 **社交登入 (Social sign-in)** 區塊新增 Facebook 連接器 (Connector)，讓使用者可用 Facebook 驗證 (Authentication) + +進一步瞭解 [社交登入體驗 (social sign-in experience)](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 連結或解除 Facebook 帳號 \{#link-or-unlink-a-facebook-account} + +使用 Account API 在你的應用程式中打造自訂帳號中心，讓已登入使用者連結或解除 Facebook 帳號。[參考 Account API 教學](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以僅啟用 Facebook 連接器 (Connector) 以供帳號連結與 API 存取，而不啟用社交登入。 +::: + +### 存取 Facebook API 並執行操作 \{#access-facebook-api-and-perform-actions} + +你的應用程式可從 Secret Vault 取得儲存的 Facebook 存取權杖 (Access token)，呼叫 Facebook API 並自動化後端任務（例如發佈內容或管理貼文）。請參考相關教學以取得 API 存取所需的權杖。 + +## 管理使用者的 Facebook 身分 \{#manage-user-s-facebook-identity} + +使用者連結 Facebook 帳號後，管理員可在 Logto Console 管理該連結： + +1. 前往 使用者管理 (User management) 並開啟該使用者的個人資料。 +2. 在 **社交連結 (Social connections)** 區塊找到 Facebook 項目並點擊 **管理 (Manage)**。 +3. 在此頁面，管理員可管理使用者的 Facebook 連結、檢視所有從 Facebook 帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。 + +:::note +Facebook 的存取權杖 (Access token) 回應不包含具體權限範圍 (Scope) 資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所需的權限範圍 (Scopes)，你的應用程式在存取 Facebook API 時就會擁有相應權限。建議你在 Facebook 開發者後台與 Logto 中都正確設定所需的權限範圍 (Scopes)，以確保應用程式具備必要存取權。 +::: + +## 參考資料 \{#reference} + +Facebook for Developers - 文件 -- [Facebook 登入 - 文件 - Facebook for Developers](https://developers.facebook.com/docs/facebook-login/) - - [手動建立登入流程](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) - - [權限指南](https://developers.facebook.com/docs/facebook-login/guides/permissions) +Facebook 登入文件 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx index e1fc871358d..c86da477c45 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/facebook/_integration.mdx @@ -1,55 +1,100 @@ -### 註冊 Facebook 開發者帳戶 \{#register-a-facebook-developer-account} +## 步驟 1：在 Facebook App Dashboard 建立應用程式 \{#step-1-set-up-an-app-on-facebook-app-dashboard} -如果你還沒有 Facebook 開發者帳戶，請[註冊為 Facebook 開發者](https://developers.facebook.com/docs/development/register/) +在你能將 Facebook 作為驗證 (Authentication) 提供者前，必須先在 Facebook 開發者平台建立應用程式，以取得 OAuth 2.0 憑證。 -### 設定 Facebook 應用程式 \{#set-up-a-facebook-app} +1. 如果你還沒有帳號，請先[註冊成為 Facebook 開發者](https://developers.facebook.com/docs/development/register/)。 +2. 前往 [Apps](https://developers.facebook.com/apps) 頁面。 +3. 點選你現有的應用程式，或[建立新應用程式](https://developers.facebook.com/docs/development/create-an-app)。 -1. 訪問 [Apps](https://developers.facebook.com/apps) 頁面。 -2. 點擊你現有的應用程式，或[創建一個新的](https://developers.facebook.com/docs/development/create-an-app)（如有需要）。 - - 選擇的[應用程式類型](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types)由你決定，但應包含 _Facebook Login_ 產品。 -3. 在應用程式儀表板頁面，滾動到「新增產品」部分，然後點擊「Facebook Login」卡片上的「設定」按鈕。 -4. 略過 Facebook Login 快速入門頁面，點擊側邊欄 ->「產品」->「Facebook Login」->「設定」。 -5. 在 Facebook Login 設定頁面，於「Valid OAuth Redirect URIs」欄位中填入 `${your_logto_origin}/callback/${connector_id}`。`connector_id` 可以在 Logto 管理控制台連接器詳細資訊頁面的頂部欄位找到。例如： - - `https://logto.dev/callback/${connector_id}` 用於生產環境 - - `https://localhost:3001/callback/${connector_id}` 用於本地環境測試 -6. 點擊右下角的「儲存變更」按鈕。 +:::tip +用例（Use case）是你的應用程式與 Meta 互動的主要方式，決定可用的 API、功能、權限與產品。如果你只需要社交驗證（取得 email 與 public_profile），請選擇「Authentication and request data from users with Facebook Login」。若你想存取 Facebook API，請選擇你偏好的用例——大多數用例在建立應用程式後也支援整合「Facebook Login for business」。 +::: -## 編寫連接器 JSON \{#compose-the-connector-json} +4. 建立應用程式後，在應用程式儀表板頁面，前往 **Use cases > Facebook Login > Settings** 或 **Facebook Login for business > Settings**。 +5. 在 **Valid OAuth Redirect URIs** 欄位填入 Logto 的 **Callback URI**（可從你的 Logto Facebook 連接器複製）。使用者以 Facebook 登入後，會被導向此處，Logto 會用授權碼完成驗證 (Authentication)。 +6. 前往 **Use cases**，點擊你的用例的 **Customize**，新增權限範圍（Scopes）。建議新增 `email` 與 `public_profile`，這是 Logto 實現 Facebook 登入所需的基本權限。 -1. 在 Facebook 應用程式儀表板頁面，點擊側邊欄 ->「設定」->「基本」。 -2. 你將在面板上看到「App ID」和「App secret」。 -3. 點擊 App secret 輸入框後的「顯示」按鈕以複製其內容。 -4. 填寫 Logto 連接器設定： - - 在 `clientId` 欄位中填入 _App ID_ 的字串。 - - 在 `clientSecret` 欄位中填入 _App secret_ 的字串。 - - 在 `scope` 欄位中填入以逗號或空格分隔的[權限](https://developers.facebook.com/docs/permissions/reference)字串列表。如果未指定 scope，預設 scope 為 `email,public_profile`。 +## 步驟 2：以用戶端憑證設定 Logto 連接器 \{#step-2-set-up-logto-connector-with-client-credentials} -## 使用 Facebook 的測試使用者測試登入 \{#test-sign-in-with-facebooks-test-users} +1. 在 Facebook App Dashboard，點選側邊欄的 **App settings > Basic**。 +2. 你會在面板上看到 **App ID** 與 **App secret**。 +3. 點擊 App secret 輸入框旁的 **Show** 按鈕以顯示並複製內容。 +4. 設定你的 Logto Facebook 連接器： + - 將 **App ID** 填入 `clientId` 欄位。 + - 將 **App secret** 填入 `clientSecret` 欄位。 + - 在 Logto 點擊 **Save and Done**，即可將你的身分系統與 Facebook 連接。 -你可以使用測試、開發者和管理員使用者的帳戶，在開發和實時[應用程式模式](https://developers.facebook.com/docs/development/build-and-test/app-modes)下測試相關應用程式的登入。 +## 步驟 3：設定權限範圍（Scopes） \{#step-3-configure-scopes} -你也可以直接[將應用程式上線](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)，以便任何 Facebook 使用者都可以使用該應用程式登入。 +權限範圍（Scopes）定義你的應用程式向使用者請求哪些權限，並控制你的專案能從他們的 Facebook 帳號存取哪些私人資料。 -- 在應用程式儀表板頁面，點擊側邊欄 ->「角色」->「測試使用者」。 -- 點擊「創建測試使用者」按鈕以創建測試使用者。 -- 點擊現有測試使用者的「選項」按鈕，你將看到更多操作，例如「更改名稱和密碼」。 +### 在 Facebook App Dashboard 設定權限範圍 \{#configure-scopes-in-facebook-app-dashboard} -## 發佈 Facebook 登入設定 \{#publish-facebook-sign-in-settings} +1. 前往 **Facebook App Dashboard > Use cases**，點擊 **Customize** 按鈕。 +2. 只新增你的應用程式所需的權限範圍。使用者會在 Facebook 使用者授權頁面 (Consent screen) 審核並授權這些權限： + - **驗證 (Authentication)（必要）**：`email` 與 `public_profile`。 + - **API 存取（選用）**：應用程式需要的其他權限範圍（例如存取 Threads API 的 `threads_content_publish`、`threads_read_replies`）。可參考 [Meta 開發者文件](https://developers.facebook.com/docs/) 了解可用服務。 -通常，只有測試、管理員和開發者使用者可以在[開發模式](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode)下使用相關應用程式登入。 +### 在 Logto 設定權限範圍 \{#configure-scopes-in-logto} -為了讓普通 Facebook 使用者在生產環境中使用應用程式登入，你可能需要將 Facebook 應用程式切換到 _[live mode](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_，具體取決於應用程式類型。 -例如，純 _business type_ 應用程式沒有「live」切換按鈕，但這不會阻礙你的使用。 +根據需求選擇以下其中一種方式： -1. 在 Facebook 應用程式儀表板頁面，點擊側邊欄 ->「設定」->「基本」。 -2. 如有需要，填寫面板上的「隱私政策 URL」和「使用者資料刪除」欄位。 -3. 點擊右下角的「儲存變更」按鈕。 -4. 點擊應用程式頂部欄位的「Live」切換按鈕。 +**選項 1：不需額外 API 權限範圍** -## 配置類型 \{#config-types} +- 保持 Logto Facebook 連接器的 `Scopes` 欄位為空。 +- 預設會請求 `email public_profile` 權限，確保 Logto 能正確取得基本使用者資訊。 -| 名稱 | 類型 | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +**選項 2：登入時請求額外權限範圍** + +- 在 **Scopes** 欄位輸入所有需要的權限範圍，並以空格分隔。 +- 此處列出的權限範圍會覆蓋預設值，因此請務必包含驗證 (Authentication) 權限：`email public_profile`。 + +**選項 3：後續漸進式請求權限範圍** + +- 使用者登入後，可透過重新啟動聯邦社交授權流程，並更新使用者儲存的權杖集，按需請求額外權限範圍。 +- 這些額外權限範圍無需填寫在 Logto Facebook 連接器的 `Scopes` 欄位，可透過 Logto 的 Social Verification API 實現。 + +依照這些步驟，Logto Facebook 連接器會精確請求你的應用程式所需的權限——不多也不少。 + +:::tip +如果你的應用程式請求這些權限以存取 Facebook API 並執行操作，請務必在 Logto Facebook 連接器啟用 **Store tokens for persistent API access**。詳情請見下一節。 +::: + +## 步驟 4：一般設定 \{#step-4-general-settings} + +以下為一些不會阻礙 Facebook 連線，但可能影響終端使用者驗證 (Authentication) 體驗的一般設定。 + +### 同步個人資料資訊 \{#sync-profile-information} + +在 Facebook 連接器中，你可以設定同步個人資料資訊（如使用者名稱與頭像）的政策。可選擇： + +- **僅於註冊時同步**：使用者首次登入時擷取一次個人資料。 +- **每次登入時皆同步**：每次使用者登入時都會更新個人資料。 + +### 儲存權杖以存取 Facebook API（選用） \{#store-tokens-to-access-facebook-apis-optional} + +若你希望存取 Facebook API 並在使用者授權下執行操作（無論是社交登入或帳號連結），Logto 需取得特定 API 權限範圍並儲存權杖。 + +1. 依照上述教學新增所需權限範圍。 +2. 在 Logto Facebook 連接器啟用 **Store tokens for persistent API access**。Logto 會將 Facebook 存取權杖安全儲存在 Secret Vault。 + +:::note +Facebook 不提供重新整理權杖 (Refresh tokens)。但啟用權杖儲存後，Logto 會在使用者驗證 (Authentication) 時自動請求長效型存取權杖（60 天）。在此期間，使用者可手動撤銷存取權杖，否則無需重新授權即可存取 Facebook API。注意：請勿在 `Scope` 欄位新增 `offline_access`，否則可能導致錯誤。 +::: + +## 步驟 5：使用 Facebook 測試用戶測試登入（選用） \{#step-5-test-sign-in-with-facebook-s-test-users-optional} + +你可以使用測試、開發者與管理員帳號測試應用程式登入。你也可以直接發佈應用程式，讓任何 Facebook 使用者都能登入。 + +1. 在 Facebook App Dashboard，點選側邊欄 **App roles > Test Users**。 +2. 點擊 **Create test users** 按鈕建立測試用戶。 +3. 點擊現有測試用戶的 **Options** 按鈕以查看更多操作，例如「更改名稱與密碼」。 + +## 步驟 6：發佈 Facebook 登入設定 \{#step-6-publish-facebook-sign-in-settings} + +通常只有測試、管理員與開發者用戶能登入應用程式。若要讓正式環境下的普通 Facebook 使用者也能登入，需將應用程式發佈。 + +1. 在 Facebook App Dashboard，點選側邊欄 **Publish**。 +2. 如有需要，填寫 **Privacy Policy URL** 與 **User data deletion** 欄位。 +3. 點擊右下角的 **Save changes** 按鈕。 +4. 點擊應用程式頂部的 **Live** 開關按鈕。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx index 91a1ed495cb..5de5ae0b18c 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/README.mdx @@ -3,7 +3,7 @@ slug: /integrations/github sidebar_label: GitHub sidebar_custom_props: darkLogoFilename: 'github-dark.svg' - description: GitHub 是一個用於軟體開發和版本控制的線上社群。 + description: GitHub 是一個用於軟體開發與版本控制的線上社群。 tutorial_config_name: GitHub OAuth app --- @@ -11,28 +11,73 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# 設定 GitHub 社交登入 +# 設定 GitHub 社交登入 (Set up social login with GitHub) -Logto 的 GitHub 社交登入官方連接器。 +整合 GitHub OAuth app 以啟用「使用 GitHub 登入」、帳號連結，以及安全存取 GitHub API。 ## 開始使用 \{#get-started} -GitHub 連接器使終端使用者能夠透過 GitHub OAuth 2.0 驗證協議，使用他們自己的 GitHub 帳戶登入你的應用程式。 +GitHub 連接器 (Connector) 支援 OAuth 2.0 整合，讓你的應用程式可以： + +- 新增「使用 GitHub 登入」驗證 (Authentication) +- 將使用者帳號與 GitHub 身分連結 +- 從 GitHub 同步使用者個人資料資訊 +- 透過 Logto Secret Vault 安全儲存權杖，存取 GitHub API 以自動化任務（例如：從你的應用程式建立 GitHub 問題、管理儲存庫） + +要設定這些驗證 (Authentication) 功能，請先在 Logto 建立 GitHub 連接器 (Connector)： + +1. 前往 Logto 控制台 > 連接器 (Connector) > 社交連接器 (Social connector)。 +2. 點擊 **新增社交連接器 (Add social connector)**，選擇 **GitHub**，點擊 **下一步 (Next)**，並依照分步教學完成整合。 -## 測試 GitHub 連接器 \{#test-github-connector} +## 運用 GitHub 連接器 (Connector) \{#utilize-the-github-connector} + +建立並連接 GitHub 連接器 (Connector) 後，你可以將其整合進終端使用者流程。根據需求選擇下列選項： + +### 啟用「使用 GitHub 登入」 \{#enable-sign-in-with-github} + +1. 在 Logto 控制台，前往 登入體驗 (Sign-in experience) > 註冊與登入 (Sign-up and sign-in)。 +2. 在 **社交登入 (Social sign-in)** 區塊新增 GitHub 連接器 (Connector)，讓使用者能以 GitHub 驗證 (Authentication)。 + +進一步了解 [社交登入體驗 (social sign-in experience)](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 連結或解除連結 GitHub 帳號 \{#link-or-unlink-a-github-account} + +使用 Account API 在你的應用程式中打造自訂帳號中心，讓已登入使用者連結或解除連結其 GitHub 帳號。[參考 Account API 教學](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) -就是這樣。GitHub 連接器現在應該可用了。別忘了 [在登入體驗中啟用社交連接器](/connectors/social-connectors/#enable-social-sign-in)。 +:::tip +你可以僅啟用 GitHub 連接器 (Connector) 以供帳號連結與 API 存取，而不啟用社交登入。 +::: + +### 存取 GitHub API 並執行操作 \{#access-github-apis-and-perform-actions} + +你的應用程式可從 Secret Vault 取得儲存的 GitHub 存取權杖 (Access token)，以呼叫 GitHub API 並自動化後端任務（例如：建立 issue、管理儲存庫或自動化工作流程）。請參考相關教學以取得 API 存取所需的權杖。 + +## 管理使用者的 GitHub 身分 \{#manage-user-s-github-identity} + +使用者連結 GitHub 帳號後，管理員可在 Logto 控制台管理該連結： + +1. 前往 Logto 控制台 > 使用者管理 (User management) 並開啟該使用者的個人資料。 +2. 在 **社交連結 (Social connections)** 區塊找到 GitHub 項目並點擊 **管理 (Manage)**。 +3. 在此頁面，管理員可管理使用者的 GitHub 連結，檢視所有從 GitHub 帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。 + +:::note +GitHub 的存取權杖 (Access token) 回應不包含具體權限範圍 (Scope) 資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所需權限範圍 (Scopes)，你的應用程式在存取 GitHub API 時就會擁有相應權限。 +::: ## 參考資料 \{#reference} - GitHub - 開發者 - 應用程式 + GitHub 開發者文件 - 關於 Apps - GitHub - 開發者 - 應用程式 - 建立 OAuth 應用程式 + GitHub 開發者文件 - 建立 OAuth App + + + + GitHub OAuth App 權限範圍 (Scopes) 文件 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx index 60f246ec637..a23301bb5b7 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/github/_integration.mdx @@ -1,36 +1,99 @@ -### 使用 GitHub 帳戶登入 \{#sign-in-with-github-account} +## 步驟 1：在 GitHub 建立 OAuth 應用程式 \{#step-1-create-an-oauth-app-on-github} -前往 [GitHub 網站](https://github.com/)並使用你的 GitHub 帳戶登入。如果你還沒有帳戶，可以註冊一個新帳戶。 +在你能將 GitHub 作為驗證 (Authentication) 提供者之前，必須先在 GitHub 上建立 OAuth 應用程式以取得 OAuth 2.0 憑證。 -### 建立並配置 OAuth 應用程式 \{#create-and-configure-oauth-app} +1. 前往 [GitHub](https://github.com/) 並使用你的帳號登入，或如有需要註冊新帳號。 +2. 導航至 [Settings > Developer settings > OAuth apps](https://github.com/settings/developers)。 +3. 點擊 **New OAuth App** 註冊新應用程式： + - **Application name**：輸入你的應用程式描述性名稱。 + - **Homepage URL**：輸入你的應用程式首頁網址。 + - **Authorization callback URL**：從 Logto GitHub 連接器複製 **Callback URI** 並貼到此處。使用者以 GitHub 登入後，將被導向此處並帶有 Logto 用於完成驗證 (Authentication) 的授權碼。 + - **Application description**：（選填）新增應用程式簡短描述。 +4. 點擊 **Register application** 以建立 OAuth 應用程式。 -按照 [建立 OAuth 應用程式](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) 指南，註冊一個新應用程式。 +:::note +建議不要勾選 **Enable Device Flow**，因為使用者若在行動裝置上以 GitHub 登入，需在 GitHub 行動應用程式中確認首次登入動作。許多 GitHub 使用者並未在手機安裝 GitHub 行動應用程式，這可能會阻斷登入流程。僅當你預期終端使用者會透過 GitHub 行動應用程式確認登入流程時才啟用此選項。詳情請參閱 [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)。 -在 **Application name** 中命名你的新 OAuth 應用程式，並填寫應用程式的 **Homepage URL**。你可以將 **Application description** 欄位留空，並將 **Authorization callback URL** 自訂為 `${your_logto_origin}/callback/${connector_id}`。`connector_id` 可以在 Logto 管理控制台連接器詳細資訊頁面的頂部欄位找到。 +更多 GitHub OAuth 應用程式設定細節，請參閱 [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)。 +::: -:::note +## 步驟 2：設定你的 Logto 連接器 \{#step-2-configure-your-logto-connector} + +在 GitHub 建立 OAuth 應用程式後，你會被導向詳細頁面，可在此複製 Client ID 並產生 Client secret。 + +1. 從 GitHub OAuth 應用程式複製 **Client ID**，貼到 Logto 的 `clientId` 欄位。 +2. 在 GitHub 點擊 **Generate a new client secret** 產生新密鑰，然後複製並貼到 Logto 的 `clientSecret` 欄位。 +3. 在 Logto 點擊 **Save and Done**，將你的身分系統與 GitHub 連接。 + +:::warning +請妥善保管你的 Client secret，切勿在前端程式碼中暴露。GitHub 的 client secret 若遺失無法找回，必須重新產生。 +::: + +## 步驟 3：設定權限範圍（Scopes，選填） \{#step-3-configure-scopes-optional} + +權限範圍（Scopes）定義你的應用程式向使用者請求的權限，並控制可從其 GitHub 帳號存取哪些資料。 + +在 Logto 的 `Scopes` 欄位中可向 GitHub 請求額外權限。根據需求選擇下列其中一種方式： + +### 選項 1：不需額外 API 權限範圍 \{#option-1-no-extra-api-scopes-needed} + +- 保持 Logto GitHub 連接器的 `Scopes` 欄位為空。 +- 預設會請求 `read:user` 權限範圍，確保 Logto 能正確取得基本使用者資訊（如電子郵件、名稱、大頭貼）。 -如果在登入時遇到錯誤訊息「The redirect_uri MUST match the registered callback URL for this application.」，請嘗試對齊 GitHub OAuth 應用程式的 Authorization Callback URL 與 Logto 應用程式的重定向 URL（當然，包括協議）來解決問題。 +### 選項 2：登入時請求額外權限範圍 \{#option-2-request-additional-scopes-at-sign-in} +- 瀏覽所有 [GitHub OAuth 應用程式可用權限範圍](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)，僅新增應用程式所需的權限範圍。 +- 在 **Scopes** 欄位輸入所有所需權限範圍，以空格分隔。 +- 此處列出的權限範圍會覆蓋預設值，因此務必包含驗證 (Authentication) 權限範圍：`read:user`。 +- 常見額外權限範圍包含： + - `repo`：完全控制私人儲存庫 + - `public_repo`：存取公開儲存庫 + - `user:email`：存取使用者電子郵件地址 + - `notifications`：存取通知 +- 請確保所有權限範圍拼寫正確且有效。錯誤或不支援的權限範圍會導致 GitHub 回傳「Invalid scope」錯誤。 + +### 選項 3：後續動態請求權限範圍 \{#option-3-request-incremental-scopes-later} + +- 使用者登入後，可隨時透過重新啟動聯邦社交授權流程並更新使用者儲存的權杖組，動態請求額外權限範圍。 +- 這些額外權限範圍無需填寫在 Logto GitHub 連接器的 `Scopes` 欄位，可透過 Logto 的 Social Verification API 實現。 + +依照上述步驟，Logto GitHub 連接器將只請求應用程式所需的權限，不多也不少。 + +:::tip +若你的應用程式請求這些權限範圍以存取 GitHub API 並執行操作，請務必在 Logto GitHub 連接器啟用 **Store tokens for persistent API access**。詳情請見下一節。 ::: -我們建議不要勾選 **Enable Device Flow** 前的方框，否則在行動裝置上使用 GitHub 登入的使用者必須在 GitHub 應用程式中確認初始登入操作。許多 GitHub 使用者並未在手機上安裝 GitHub 行動應用程式，這可能會阻礙登入流程。如果你希望終端使用者確認他們的登入流程，請忽略我們的建議。詳情請參閱 [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)。 +## 步驟 4：一般設定 \{#step-4-general-settings} + +以下為不會阻礙與 GitHub 連線，但可能影響終端使用者驗證 (Authentication) 體驗的一般設定。 + +### 同步個人檔案資訊 \{#sync-profile-information} -### 管理 OAuth 應用程式 \{#managing-oauth-apps} +在 GitHub 連接器中，你可以設定同步個人檔案資訊（如使用者名稱與大頭貼）的政策。可選擇： -前往 [OAuth Apps 頁面](https://github.com/settings/developers)，你可以新增、編輯或刪除現有的 OAuth 應用程式。 -你也可以在 OAuth 應用程式詳細資訊頁面中找到 `Client ID` 並生成 `Client secrets`。 +- **僅註冊時同步**：使用者首次登入時僅同步一次個人資訊。 +- **每次登入時皆同步**：每次使用者登入時都會更新個人資訊。 -### 配置你的連接器 \{#configure-your-connector} +### 儲存權杖以存取 GitHub API（選填） \{#store-tokens-to-access-github-apis-optional} + +若你希望在取得使用者授權後（無論是社交登入或帳號連結）存取 GitHub API 並執行操作，Logto 需取得特定 API 權限範圍並儲存權杖。 + +1. 依照上述說明新增所需權限範圍。 +2. 在 Logto GitHub 連接器啟用 **Store tokens for persistent API access**。Logto 會將 GitHub 存取權杖安全儲存在 Secret Vault。 + +:::note +當你如本教學所述使用 GitHub **OAuth App** 時，無法從 GitHub 取得重新整理權杖（Refresh token），因為其存取權杖（Access token）除非使用者手動撤銷，否則不會過期。因此，無需在 `Scopes` 欄位新增 `offline_access`，否則可能導致錯誤。 + +若你希望存取權杖會過期或使用重新整理權杖，請考慮改用 **GitHub App** 整合。瞭解 [GitHub App 與 OAuth App 的差異](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)。 +::: -在前一節提到的 OAuth 應用程式詳細資訊頁面中，填寫 `clientId` 和 `clientSecret` 欄位，使用獲得的 _Client ID_ 和 _Client Secret_。 +## 步驟 5：測試你的整合（選填） \{#step-5-test-your-integration-optional} -`scope` 是一個以空格分隔的 [scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) 列表。如果未提供，scope 預設為 `read:user`。 +在正式上線前，請測試你的 GitHub 整合： -### 配置類型 \{#config-types} +1. 在 Logto 開發租戶中使用此連接器。 +2. 驗證使用者能以 GitHub 登入。 +3. 檢查請求的權限範圍是否正確。 +4. 若有儲存權杖，請測試 API 呼叫。 -| 名稱 | 類型 | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | +GitHub OAuth 應用程式可立即與任何 GitHub 使用者帳號配合使用——不需像其他平台那樣申請測試使用者或應用程式審核。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx index 24075bdefac..1d9f0e0d856 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/README.mdx @@ -2,8 +2,8 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: - description: Google 是主要的搜尋引擎技術和電子郵件服務提供者。 -tutorial_config_name: Google OAuth app + description: Google 是主要的搜尋引擎技術與電子郵件服務提供者。 +tutorial_config_name: Google OAuth 應用程式 --- import GuideTip from '../../fragments/_guide-tip.mdx'; @@ -12,14 +12,66 @@ import Integration from './_integration.mdx'; # 設定 Google 社交登入 -Google 連接器為你的應用程式提供了一種簡潔的方式來使用 Google 的 OAuth 2.0 驗證系統。 +整合 Google OAuth 2.0 驗證 (Authentication) 系統，啟用 Google 登入、帳號連結，以及安全存取 Google API。 +## 開始使用 \{#get-started} + +Google 連接器 (Connector) 支援 OAuth 2.0 整合，讓你的應用程式可以： + +- 新增「使用 Google 登入」驗證 (Authentication) +- 將使用者帳號與 Google 身分連結 +- 從 Google 同步使用者個人資料資訊 +- 透過 Logto Secret Vault 安全儲存權杖，存取 Google API 以自動化任務（例如：編輯 Google 文件、在你的應用程式中管理行事曆事件） + +要設定這些驗證 (Authentication) 功能，請先在 Logto 建立 Google 連接器 (Connector)： + +1. 前往 Logto 控制台 > 連接器 (Connector) > 社交連接器 (Social connector)。 +2. 點擊 **新增社交連接器**，選擇 **Google**，點擊 **下一步**，並依照分步教學完成整合。 + -## 參考資料 \{#references} +## 使用 Google 連接器 (Connector) \{#utilize-the-google-connector} + +建立 Google 連接器 (Connector) 並與 Google 連結後，你可以將其整合進終端使用者流程。根據需求選擇合適的選項： + +### 啟用「使用 Google 登入」 \{#enable-sign-in-with-google} + +1. 在 Logto 控制台，前往 登入體驗 > 註冊與登入。 +2. 在 **社交登入** 區塊新增 Google 連接器 (Connector)，讓使用者可用 Google 驗證 (Authentication)。 +3. 可選擇在登入與註冊頁啟用 **Google One Tap**，提供更流暢的驗證 (Authentication) 體驗。 + +進一步了解 [社交登入體驗](/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 連結或解除連結 Google 帳號 \{#link-or-unlink-a-google-account} + +使用 Account API 在你的應用程式中打造自訂帳號中心，讓已登入使用者連結或解除 Google 帳號。[參考 Account API 教學](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以僅啟用 Google 連接器 (Connector) 以供帳號連結與 API 存取，不必啟用社交登入。 +::: + +### 存取 Google API 並執行操作 \{#access-google-apis-and-perform-actions} + +你的應用程式可從 Secret Vault 取得儲存的 Google 存取權杖 (Access token)，呼叫 Google API 並自動化後端任務（例如：管理 Google 雲端硬碟檔案、建立行事曆事件、或透過 Gmail 寄送郵件）。請參考相關教學以取得 API 存取所需的權杖。 + +## 管理使用者的 Google 身分 \{#manage-user-s-google-identity} + +使用者連結 Google 帳號後，管理員可在 Logto 控制台管理該連結： + +1. 前往 Logto 控制台 > 使用者管理 並開啟該使用者的個人資料。 +2. 在 **社交連結** 區塊找到 Google 項目並點擊 **管理**。 +3. 在此頁面，管理員可管理使用者的 Google 連結、檢視所有從 Google 帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。 + +## 參考資料 \{#reference} - Google Identity: 設定 OAuth 2.0 + Google 身分：設定 OAuth 2.0 + + + Google 身分服務（One Tap） + + +Google Cloud Console diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx index 8057203e846..9aa79ffb388 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/google/_integration.mdx @@ -1,85 +1,160 @@ -## 在 Google API Console 中設定專案 \{#set-up-a-project-in-the-google-api-console} +## 步驟 1：在 Google Auth Platform 建立專案 \{#step-1-create-a-project-on-google-auth-platform} + +在你能將 Google 作為驗證 (Authentication) 提供者之前，必須先在 Google Cloud Console 建立專案以取得 OAuth 2.0 憑證。如果你已有專案，可跳過此步驟。 + +1. 前往 [Google Cloud Console](https://console.cloud.google.com/) 並使用你的 Google 帳戶登入。 +2. 點擊頂部選單列的 **選擇專案（Select a project）** 按鈕，然後點擊 **新增專案（New Project）** 以建立專案。 +3. 在新建立的專案中，前往 **API 與服務 > OAuth 同意畫面（APIs & Services > OAuth consent screen）** 來設定你的應用程式： + - **應用程式資訊（App information）**：輸入要顯示於同意頁面的 **應用程式名稱（Application name）** 與 **支援電子郵件（Support email）** + - **受眾（Audience）**：選擇你偏好的受眾類型： + - **內部（Internal）** - 僅限你組織內的 Google Workspace 使用者 + - **外部（External）** - 任何 Google 使用者皆可（正式上線需驗證） + - **聯絡資訊（Contact information）**：提供電子郵件地址，讓 Google 能通知你專案的任何變更 + - 勾選 **我同意 Google 的政策（I agree to Google's policies）** 完成基本設定 +4. （選填）前往 **品牌設定（Branding）** 區段，編輯產品資訊並上傳你的 **應用程式標誌（App logo）**，該標誌將顯示於 OAuth 同意頁面，協助使用者辨識你的應用程式。 + +:::tip +如果你選擇 **外部（External）** 受眾類型，開發期間需新增測試使用者，並於正式上線時發佈應用程式。 +::: + +## 步驟 2：建立 OAuth 2.0 憑證 \{#step-2-create-oauth-2-0-credentials} + +在 Google Cloud Console 的 [憑證（Credentials）](https://console.cloud.google.com/apis/credentials) 頁面，為你的應用程式建立 OAuth 憑證。 + +1. 點擊 **建立憑證（Create Credentials）> OAuth 用戶端 ID（OAuth client ID）**。 +2. 選擇 **網頁應用程式（Web application）** 作為應用程式類型。 +3. 填寫 OAuth 用戶端的 **名稱（Name）**。這僅用於識別憑證，不會顯示給終端使用者。 +4. 設定授權的 URI： + - **授權的 JavaScript 來源（Authorized JavaScript origins）**：新增你的 Logto 實例來源（例如 `https://your-logto-domain.com`） + - **授權的重新導向 URI（Authorized redirect URIs）**：新增 Logto 的 **Callback URI**（可從 Logto Google 連接器複製） +5. 點擊 **建立（Create）** 以產生 OAuth 用戶端。 + +## 步驟 3：用憑證設定 Logto 連接器 \{#step-3-configure-logto-connector-with-credentials} + +建立 OAuth 用戶端後，Google 會顯示一個包含憑證的視窗： + +1. 複製 **Client ID** 並貼到 Logto 的 `clientId` 欄位 +2. 複製 **Client secret** 並貼到 Logto 的 `clientSecret` 欄位 +3. 在 Logto 點擊 **儲存並完成（Save and Done）**，即可將你的身分系統與 Google 連接 + +:::warning +請妥善保管你的 client secret，切勿在前端程式碼中暴露。如果洩漏，請立即產生新密鑰。 +::: + +## 步驟 4：設定權限範圍（Scopes） \{#step-4-configure-scopes} + +權限範圍（Scopes）定義你的應用程式向使用者請求哪些權限，並控制可從其 Google 帳戶存取哪些資料。 + +### 在 Google Cloud Console 設定權限範圍 \{#configure-scopes-in-google-cloud-console} + +1. 前往 **API 與服務 > OAuth 同意畫面 > 權限範圍（APIs & Services > OAuth consent screen > Scopes）**。 +2. 點擊 **新增或移除權限範圍（Add or Remove Scopes）**，僅選擇應用程式所需的權限範圍： + - **驗證 (Authentication)（必要）**： + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - **API 存取（選填）**：根據應用程式需求新增其他權限範圍（如 Drive、Calendar、YouTube）。可瀏覽 [Google API Library](https://console.cloud.google.com/apis/library) 查找可用服務。若需存取進階 Google API，請先在 Google API Library 啟用對應 API（如 Google Drive API、Gmail API、Calendar API）。 +3. 點擊 **更新（Update）** 確認選擇。 +4. 點擊 **儲存並繼續（Save and Continue）** 套用變更。 -- 訪問 [Google API Console](https://console.developers.google.com) 並使用你的 Google 帳戶登入。 -- 點擊頂部選單欄的 **Select a project** 按鈕，然後點擊 **New Project** 按鈕來建立專案。 -- 在新建立的專案中，點擊 **APIs & Services** 進入 **APIs & Services** 選單。 +### 在 Logto 設定權限範圍 \{#configure-scopes-in-logto} -## 配置你的使用者授權頁面 \{#configure-your-consent-screen} +根據需求選擇以下其中一種方式： -### 配置並註冊你的應用程式 \{#configure-and-register-your-application} +**選項 1：不需額外 API 權限範圍** -- 在左側 **APIs & Services** 選單中，點擊 **OAuth consent screen** 按鈕。 -- 選擇你想要的 **User Type**，然後點擊 **Create** 按鈕。（注意：如果選擇 **External** 作為 **User Type**，稍後需要新增測試使用者。） +- 保持 Logto Google 連接器的 `Scopes` 欄位為空。 +- 預設會請求 `openid profile email` 權限範圍，確保 Logto 能正確取得基本使用者資訊。 -現在你將進入 **Edit app registration** 頁面。 +**選項 2：登入時請求額外權限範圍** -### 編輯應用程式註冊 \{#edit-app-registration} +- 在 **Scopes** 欄位輸入所有所需權限範圍，以空格分隔。 +- 此處填寫的權限範圍會覆蓋預設值，因此請務必包含驗證 (Authentication) 權限範圍：`https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid`。 +- 請使用完整的權限範圍 URL。例如：`https://www.googleapis.com/auth/calendar.readonly`。 -#### 配置 OAuth 使用者授權頁面 \{#config-oauth-consent-screen} +**選項 3：後續漸進式請求權限範圍** -- 按照指示填寫 **OAuth consent screen** 表單。 -- 點擊 **SAVE AND CONTINUE** 繼續。 +- 使用者登入後，可透過重新啟動聯邦社交授權流程並更新使用者的權杖組，按需請求額外權限範圍。 +- 這些額外權限範圍無需預先填寫在 Logto Google 連接器的 `Scopes` 欄位，可透過 Logto 的 Social Verification API 實現。 -#### 配置權限範圍 (Scopes) \{#config-scopes} +依照這些步驟，Logto Google 連接器會精確請求應用程式所需的權限，不多也不少。 -- 點擊 **ADD OR REMOVE SCOPES** 並在彈出抽屜中選擇 `../auth/userinfo.email`、`../auth/userinfo.profile` 和 `openid`，然後點擊 **UPDATE** 完成。建議考慮新增所有可能使用的權限範圍，否則某些配置中新增的權限範圍可能無法運作。 -- 根據需要填寫表單。 -- 點擊 **SAVE AND CONTINUE** 繼續。 +:::tip +若你的應用程式請求這些權限範圍以存取 Google API 並執行操作，請務必在 Logto Google 連接器啟用 **持久 API 存取權杖儲存（Store tokens for persistent API access）**。詳情請見下一節。 +::: -#### 新增測試使用者（僅限 External 使用者類型）\{#add-test-users-external-user-type-only} +## 步驟 5：自訂驗證 (Authentication) 提示 \{#step-5-customize-authentication-prompts} -- 點擊 **ADD USERS** 並新增測試使用者，以允許這些使用者在測試時存取你的應用程式。 -- 點擊 **SAVE AND CONTINUE** 繼續。 +在 Logto 設定 **Prompts** 以控制使用者驗證 (Authentication) 體驗。Prompts 是一個字串陣列，指定所需的使用者互動類型： -現在你應該已經配置好 Google OAuth 2.0 使用者授權頁面。 +- `none` - 授權伺服器不顯示任何驗證 (Authentication) 或同意畫面。若使用者尚未驗證 (Authentication) 或未預先同意所請求的權限範圍，則會回傳錯誤。可用於檢查現有驗證 (Authentication) / 同意狀態。 +- `consent` - 授權伺服器會在回傳資訊給用戶端前提示使用者同意。啟用 Google API **離線存取（offline access）** 時必須使用。 +- `select_account` - 授權伺服器會提示使用者選擇帳戶。適用於有多個 Google 帳戶的使用者選擇登入帳戶。 -## 獲取 OAuth 2.0 憑證 \{#obtain-oauth-20-credentials} +## 步驟 6：一般設定 \{#step-6-general-settings} -- 在左側 **APIs & Services** 選單中，點擊 **Credentials** 按鈕。 -- 在 **Credentials** 頁面，點擊頂部選單欄的 **+ CREATE CREDENTIALS** 按鈕，然後選擇 **OAuth client ID**。 -- 在 **Create OAuth client ID** 頁面，選擇 **Web application** 作為應用程式類型。 -- 填寫應用程式的基本資訊。 -- 點擊 **+ Add URI** 以在 **Authorized JavaScript origins** 部分新增授權網域。這是你的 Logto 授權頁面將提供服務的網域。在我們的例子中，這將是 `${your_logto_origin}`，例如 `https://logto.dev`。 -- 在 **Authorized redirect URIs** 部分點擊 **+ Add URI** 來設定 **Authorized redirect URIs**，這會在使用者登入後將其重定向到應用程式。在我們的例子中，這將是 `${your_logto_endpoint}/callback/${connector_id}`，例如 `https://logto.dev/callback/${connector_id}`。`connector_id` 可以在 Logto Admin Console 連接器詳細資訊頁面的頂部欄位找到。 -- 點擊 **Create** 完成，然後你將獲得 **Client ID** 和 **Client Secret**。 +以下是一些不會阻礙 Google 連線，但可能影響終端使用者驗證 (Authentication) 體驗的通用設定。 -## 配置你的連接器 \{#configure-your-connector} +### 同步個人檔案資訊 \{#sync-profile-information} -在前一節提到的 OAuth 應用程式詳細資訊頁面中，使用獲得的 _Client ID_ 和 _Client Secret_ 填寫 `clientId` 和 `clientSecret` 欄位。 +在 Google 連接器中，你可以設定同步個人檔案資訊（如使用者名稱與頭像）的政策。可選擇： -`scope` 是一個以空格分隔的 [權限範圍 (scopes)](https://developers.google.com/identity/protocols/oauth2/scopes) 列表。如果未提供，預設權限範圍為 `openid profile email`。 +- **僅註冊時同步（Only sync at sign-up）**：僅於使用者首次登入時取得個人資訊。 +- **每次登入時同步（Always sync at sign-in）**：每次登入時都會更新個人資訊。 -`prompts` 是一個字串數組，指定所需的使用者互動類型。字串可以是以下值之一： +### 儲存權杖以存取 Google API（選填） \{#store-tokens-to-access-google-apis-optional} -- `none`：授權伺服器不顯示任何驗證或使用者授權頁面；如果使用者尚未驗證且未預先配置請求權限範圍的授權，將返回錯誤。你可以使用 none 來檢查現有的驗證和/或授權。 -- `consent`：授權伺服器在向客戶端返回資訊之前提示使用者授權。 -- `select_account`：授權伺服器提示使用者選擇一個使用者帳戶。這允許在授權伺服器上有多個帳戶的使用者選擇他們可能有當前會話的多個帳戶之一。 +若你希望存取 [Google API](https://console.cloud.google.com/apis/library) 並在使用者授權下執行操作（無論是社交登入或帳號連結），Logto 需取得特定 API 權限範圍並儲存權杖。 -### 配置類型 \{#config-types} +1. 在 Google Cloud Console 的 OAuth 同意畫面設定及 Logto Google 連接器中新增所需權限範圍。 +2. 在 Logto Google 連接器啟用 **持久 API 存取權杖儲存（Store tokens for persistent API access）**。Logto 會將 Google 存取權杖與重新整理權杖安全儲存於 Secret Vault。 +3. 為確保能取得重新整理權杖，請如下設定 Logto Google 連接器： + - **Prompts** 包含 `consent` + - 啟用 **離線存取（Offline Access）** -| 名稱 | 類型 | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | +:::warning +你不需要在 Logto 的 `Scope` 欄位加入 `offline_access` —— 這麼做可能會導致錯誤。Google 在啟用離線存取時會自動使用 `access_type=offline`。 +::: -## 啟用 Google One Tap \{#enable-google-one-tap} +## 步驟 7：啟用 Google One Tap（選填） \{#step-7-enable-google-one-tap-optional} -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) 是一種安全且簡單的方式，讓使用者使用其 Google 帳戶登入你的網站或應用程式。 +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) 是一種安全且簡便的方式，讓使用者透過彈出式介面以 Google 帳戶登入你的网站。 -一旦你設置好 Google 連接器，你將在連接器詳細資訊頁面看到 Google One Tap 的卡片。你可以通過切換開關在註冊和登入頁面中啟用 Google One Tap。 +當你完成 Google 連接器設定後，會在連接器詳情頁看到 Google One Tap 卡片。切換開關即可啟用 Google One Tap。 -啟用 Google One Tap 後，你可以配置以下選項： +### Google One Tap 設定選項 \{#google-one-tap-configuration-options} -- **如果可能，自動選擇憑證**：如果滿足 [某些條件](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out)，自動使用 Google 帳戶登入使用者。 -- **如果使用者在外部點擊/點擊，取消提示**：如果使用者在提示外部點擊或點擊，關閉 Google One Tap 提示。如果禁用，使用者必須點擊關閉按鈕以關閉提示。 -- **在 ITP 瀏覽器上啟用升級的 One Tap UX**：在智能追蹤防護 (ITP) 瀏覽器上啟用升級的 Google One Tap 使用者體驗。更多資訊請參閱[此頁面](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers)。 +- **自動選擇憑證（Auto-select credential if possible）** - 若 [符合特定條件](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out)，自動以 Google 帳戶登入使用者 +- **使用者點擊 / 點觸外部時取消提示（Cancel the prompt if user clicks/taps outside）** - 若使用者點擊或點觸提示框外部則關閉 Google One Tap 提示。若停用，使用者必須點擊關閉按鈕才能關閉提示。 +- **在 ITP 瀏覽器啟用升級版 One Tap UX（Enable Upgraded One Tap UX on ITP browsers）** - 在啟用 Intelligent Tracking Prevention (ITP) 的瀏覽器上啟用升級版 Google One Tap 體驗。詳情請參閱 [官方文件](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers)。 -:::caution -確保在 OAuth 使用者授權頁面配置中將你的伺服器來源新增到 **Authorized JavaScript origins** 部分。否則，Google One Tap 無法顯示。 +:::warning +請務必將你的網域加入 OAuth 用戶端設定的 **授權的 JavaScript 來源（Authorized JavaScript origins）**。否則 Google One Tap 將無法顯示。 ::: +### Google One Tap 的重要限制 \{#important-limitations-with-google-one-tap} + +若你同時啟用 **持久 API 存取權杖儲存（Store tokens for persistent API access）** 與 **Google One Tap**，你不會自動取得存取權杖或所請求的權限範圍。 + +Google One Tap 登入（不同於標準「以 Google 登入」按鈕）**不會**發放 OAuth 存取權杖。它僅回傳一個 ID 權杖（簽署過的 JWT），可驗證使用者身分，但無法授予 API 存取權。 + +若需讓 Google One Tap 使用者存取 Google API，可在使用者以 Google One Tap 登入後，透過 Logto 的 Social Verification API 重新啟動聯邦社交授權流程。如此可按需請求額外權限範圍並更新使用者的權杖組，無需預先在 Logto Google 連接器填寫這些權限範圍。這種方式實現漸進式授權，僅在應用程式實際需要時才提示使用者額外權限。 + +詳情請參閱 [Google One Tap 限制](https://developers.google.com/identity/gsi/web/guides/overview) 官方文件。 + +## 步驟 8：測試並發佈你的應用程式 \{#step-8-test-and-publish-your-app} + +### 內部應用程式 \{#for-internal-apps} + +若你的 Google **受眾（Audience）** 類型設為 **內部（Internal）**，應用程式僅對你組織內的 Google Workspace 使用者開放。你可用組織內任一帳戶進行測試。 + +### 外部應用程式 \{#for-external-apps} + +若你的 **受眾（Audience）** 類型為 **外部（External）**： + +1. **開發期間**：前往 **OAuth 同意畫面 > 測試使用者（Test users）**，新增測試使用者電子郵件地址。僅這些使用者可登入你的應用程式。 +2. **正式上線**：在 OAuth 同意畫面區段點擊 **發佈應用程式（Publish App）**，讓所有 Google 帳戶使用者皆可存取。 + :::note -要在你的网站中啟用 Google One Tap（超出 Logto 登入體驗），此功能正在開發中。請關注更新。 +具有敏感或受限權限範圍的應用程式，可能需經 Google 驗證後才能發佈。此流程可能需時數週。 ::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx index 972293a7df5..18a93234569 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/README.mdx @@ -1,30 +1,40 @@ --- slug: /integrations/oauth2 -sidebar_label: OAuth 2.0 (社交) +sidebar_label: OAuth 2.0（社交） sidebar_custom_props: - description: OAuth 2.0 授權框架使第三方應用程式能夠獲得對 HTTP 服務的有限存取。 + description: OAuth 2.0 授權框架讓第三方應用程式能取得對 HTTP 服務的有限存取權。 logoFilename: 'oauth.svg' tutorial_name: OAuth2 -tutorial_config_name: Standard OAuth 2.0 app +tutorial_config_name: 標準 OAuth 2.0 應用程式 --- import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# 設定 OAuth 2.0 協議的社交登入 +# 設定 OAuth 2.0 協議社交登入 (Set up social login with OAuth 2.0 protocol) -Logto 的官方 OAuth 2.0 協議連接器。 +官方 Logto OAuth 2.0 協議連接器。 ## 開始使用 \{#get-started} -OAuth 連接器使 Logto 能夠連接支援 OAuth 2.0 協議的任意社交身分提供者。 +OAuth 連接器讓 Logto 能連接任何支援 OAuth 2.0 協議的社交身分提供者。使用 OAuth 連接器，你可以讓應用程式： + +- 新增社交登入按鈕 +- 將使用者帳號與社交身分連結 +- 從社交提供者同步使用者個人資料資訊 +- 透過 Logto Secret Vault 安全儲存權杖，存取第三方 API 以自動化任務（例如：編輯 Google 文件、管理應用程式中的行事曆事件） + +要設定這些驗證 (Authentication) 功能，請先在 Logto 建立一個 OAuth 2.0 連接器： + +1. 前往 Logto 控制台 > 連接器 > 社交連接器。 +2. 點擊 **新增社交連接器**，選擇 **OAuth 2.0**，點擊 **下一步**，並依照分步教學完成整合。 :::note -OAuth 連接器是 Logto 中一種特殊的連接器，你可以新增一些基於 OAuth 協議的連接器。 +OAuth 連接器是 Logto 中一種特殊的連接器，你可以新增多個基於 OAuth 協議的連接器。 ::: @@ -32,4 +42,6 @@ OAuth 連接器是 Logto 中一種特殊的連接器，你可以新增一些基 ## 參考資料 \{#reference} -OAuth 2.0 授權框架 + + OAuth 2.0 授權框架 (The OAuth 2.0 Authorization Framework) + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx index 4c8ee2fc44a..94daef7e067 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oauth2/_integration.mdx @@ -1,36 +1,36 @@ ## 建立你的 OAuth 應用程式 \{#create-your-oauth-app} -當你打開此頁面時，我們相信你已經知道要連接哪個社交身分提供者。首先要確認的是該身分提供者是否支援 OAuth 協議，這是配置有效連接器的前提。然後，按照身分提供者的指示註冊並建立相關的 OAuth 授權應用程式。 +當你開啟本頁時，我們相信你已經知道要連接哪個社交身分提供者。首先，請確認該身分提供者支援 OAuth 協議，這是設定有效連接器的前提。然後，依照身分提供者的指引註冊並建立用於 OAuth 授權的相關應用程式。 -## 配置你的連接器 \{#configure-your-connector} +## 設定你的連接器 (Connector) \{#configure-your-connector} -出於安全考量，我們僅支援「Authorization Code」授權類型，這完全適合 Logto 的場景。 +基於安全考量，我們**僅支援**「授權碼 (Authorization Code)」授權類型，這也能完美符合 Logto 的使用情境。 `clientId` 和 `clientSecret` 可以在你的 OAuth 應用程式詳細資訊頁面找到。 -_clientId_：客戶端 ID 是在註冊時用來識別客戶端應用程式的唯一識別符。授權伺服器使用此 ID 驗證客戶端應用程式的身分，並將任何授權的存取權杖與該特定客戶端應用程式關聯。 +_clientId_：client ID 是在向授權伺服器註冊時用來識別用戶端應用程式的唯一識別碼。授權伺服器會利用這個 ID 來驗證用戶端應用程式的身分，並將任何授權的存取權杖 (Access token) 與該特定用戶端應用程式關聯。 -_clientSecret_：客戶端密鑰是在註冊時由授權伺服器發給客戶端應用程式的機密金鑰。客戶端應用程式使用此密鑰在請求存取權杖時向授權伺服器進行驗證。客戶端密鑰被視為機密資訊，應始終保持安全。 +_clientSecret_：client secret 是授權伺服器在註冊時發給用戶端應用程式的機密金鑰。用戶端應用程式在請求存取權杖 (Access token) 時，會使用這個金鑰向授權伺服器驗證自身身分。client secret 屬於機密資訊，必須隨時妥善保管。 -_tokenEndpointAuthMethod_：權杖端點驗證方法是客戶端應用程式在請求存取權杖時用來向授權伺服器進行驗證的方法。要發現支援的方法，請查閱 OAuth 2.0 服務提供者的 OpenID Connect 發現端點中的 `token_endpoint_auth_methods_supported` 欄位，或參考 OAuth 2.0 服務提供者提供的相關文件。 +_tokenEndpointAuthMethod_：權杖端點驗證方法是用戶端應用程式在請求存取權杖 (Access token) 時，向授權伺服器驗證自身身分所用的方法。請參考 OAuth 2.0 服務提供者的 OpenID Connect 探索端點中的 `token_endpoint_auth_methods_supported` 欄位，或查閱相關文件以瞭解支援的方法。 -_clientSecretJwtSigningAlgorithm (可選)_：僅在 `tokenEndpointAuthMethod` 為 `client_secret_jwt` 時需要。客戶端密鑰 JWT 簽名算法是客戶端應用程式在權杖請求期間用來簽署發送給授權伺服器的 JWT。 +_clientSecretJwtSigningAlgorithm (選填)_：僅當 `tokenEndpointAuthMethod` 為 `client_secret_jwt` 時需要。client secret JWT 簽章演算法用於用戶端應用程式在權杖請求 (Token request) 時簽署傳送給授權伺服器的 JWT。 -_scope_：權限範圍參數用來指定客戶端應用程式請求存取的資源和權限集。權限範圍參數通常定義為一個以空格分隔的值列表，代表特定的權限。例如，權限範圍值 "read write" 可能表示客戶端應用程式請求對使用者資料的讀取和寫入存取。 +_scope_：scope 參數用於指定用戶端應用程式請求存取的資源與權限範圍 (Scopes)。scope 通常是一串以空格分隔的值，代表特定權限。例如，scope 設為 "read write" 可能表示用戶端應用程式請求讀取與寫入使用者資料的權限。 -你應該在社交供應商的文件中找到 `authorizationEndpoint`、`tokenEndpoint` 和 `userInfoEndpoint`。 +你應該能在社交服務商的文件中找到 `authorizationEndpoint`、`tokenEndpoint` 和 `userInfoEndpoint`。 -_authenticationEndpoint_：此端點用來啟動驗證過程。驗證過程通常涉及使用者登入並授權客戶端應用程式存取其資源。 +_authenticationEndpoint_：此端點用於啟動驗證流程。驗證流程通常包含使用者登入並授權用戶端應用程式存取其資源。 -_tokenEndpoint_：此端點由客戶端應用程式用來獲取可用於存取請求資源的存取權杖。客戶端應用程式通常會向權杖端點發送包含授權類型和授權碼的請求以接收存取權杖。 +_tokenEndpoint_：此端點供用戶端應用程式取得可用於存取所請求資源的存取權杖 (Access token)。用戶端應用程式通常會帶著授權碼 (Authorization code) 與授權類型 (Grant type) 請求權杖。 -_userInfoEndpoint_：此端點由客戶端應用程式用來獲取有關使用者的其他資訊，例如全名、電子郵件地址或個人資料圖片。使用者資訊端點通常在客戶端應用程式從權杖端點獲取存取權杖後訪問。 +_userInfoEndpoint_：此端點供用戶端應用程式取得使用者的額外資訊，例如全名、電子郵件或大頭貼。通常在取得存取權杖 (Access token) 後存取 user info 端點。 -Logto 還提供一個 `profileMap` 欄位，使用者可以自訂從社交供應商的資料映射，這些資料通常不是標準的。鍵是 Logto 的標準使用者資料欄位名稱，對應的值應該是社交資料的欄位名稱。在目前階段，Logto 只關注社交資料中的 'id'、'name'、'avatar'、'email' 和 'phone'，其中只有 'id' 是必需的，其他是可選欄位。 +Logto 也提供 `profileMap` 欄位，讓你自訂社交服務商回傳的使用者資料欄位對應（通常格式不標準）。key 為 Logto 標準使用者資料欄位名稱，value 則為社交服務商的欄位名稱。目前 Logto 只關注社交資料中的 'id'、'name'、'avatar'、'email' 和 'phone'，其中僅 'id' 為必填，其餘為選填。 -`responseType` 和 `grantType` 在授權碼授權類型中只能是固定值，因此我們將它們設為可選，並會自動填入預設值。 +`responseType` 和 `grantType` 僅能為授權碼 (Authorization code) 類型的固定值，因此我們將其設為選填，預設值會自動填入。 -例如，你可以找到 [Google 使用者資料回應](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload)，因此其 `profileMap` 應如下所示： +舉例來說，你可以參考 [Google 使用者資料回應](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload)，其 `profileMap` 應如下： ```json { @@ -41,31 +41,97 @@ Logto 還提供一個 `profileMap` 欄位，使用者可以自訂從社交供應 :::note -我們提供了一個可選的 `customConfig` 鍵來放置你的自訂參數。 -每個社交身分提供者可能在 OAuth 標準協議上有自己的變體。如果你想要的社交身分提供者嚴格遵循 OAuth 標準協議，那麼你不需要關心 `customConfig`。 +我們提供了**選填**的 `customConfig` 欄位，讓你放自訂參數。 +每個社交身分提供者在 OAuth 標準協議上可能有自己的變體。如果你的目標身分提供者完全遵循 OAuth 標準協議，則無需理會 `customConfig`。 ::: -## 配置類型 \{#config-types} - -| 名稱 | 類型 | 必需 | -| ------------------------- | ----------------------- | ---- | -| authorizationEndpoint | string | 是 | -| userInfoEndpoint | string | 是 | -| clientId | string | 是 | -| clientSecret | string | 是 | -| tokenEndpointResponseType | enum | 否 | -| responseType | string | 否 | -| grantType | string | 否 | -| tokenEndpoint | string | 否 | -| scope | string | 否 | -| customConfig | Record\ | 否 | -| profileMap | ProfileMap | 否 | - -| ProfileMap 欄位 | 類型 | 必需 | 預設值 | -| --------------- | ------ | ---- | ------ | -| id | string | 否 | id | -| name | string | 否 | name | -| avatar | string | 否 | avatar | -| email | string | 否 | email | -| phone | string | 否 | phone | +## 設定類型 (Config types) \{#config-types} + +| 名稱 | 類型 | 必填 | +| ------------------------- | ----------------------- | ----- | +| authorizationEndpoint | string | true | +| userInfoEndpoint | string | true | +| clientId | string | true | +| clientSecret | string | true | +| tokenEndpointResponseType | enum | false | +| responseType | string | false | +| grantType | string | false | +| tokenEndpoint | string | false | +| scope | string | false | +| customConfig | Record\ | false | +| profileMap | ProfileMap | false | + +| ProfileMap 欄位 | 類型 | 必填 | 預設值 | +| --------------- | ------ | ----- | ------ | +| id | string | false | id | +| name | string | false | name | +| avatar | string | false | avatar | +| email | string | false | email | +| phone | string | false | phone | + +## 一般設定 \{#general-settings} + +以下是一些不會阻礙你連接身分提供者，但可能影響終端使用者驗證體驗的通用設定。 + +### 社交按鈕名稱與 Logo \{#social-button-name-and-logo} + +如果你想在登入頁顯示社交按鈕，可以設定社交身分提供者的**名稱**與**Logo**（深色模式與淺色模式）。這有助於使用者辨識社交登入選項。 + +### 身分提供者名稱 \{#identity-provider-name} + +每個社交連接器都有唯一的身分提供者 (IdP, Identity Provider) 名稱，用於區分使用者身分。常見連接器會使用固定 IdP 名稱，自訂連接器則需填入唯一值。詳情請參閱 [IdP 名稱說明](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name)。 + +### 同步個人資料資訊 \{#sync-profile-information} + +在 OAuth 連接器中，你可以設定同步個人資料（如使用者名稱與大頭貼）的政策。可選擇： + +- **僅於註冊時同步**：使用者首次登入時取得一次個人資料。 +- **每次登入時皆同步**：每次登入時都會更新個人資料。 + +### 儲存權杖以存取第三方 API（選填） \{#store-tokens-to-access-third-party-apis-optional} + +如果你想存取身分提供者的 API 並以使用者授權執行操作（無論是社交登入或帳號連結），Logto 需要取得特定 API 權限範圍 (Scopes) 並儲存權杖。 + +1. 依上述說明在 **scope** 欄位加入所需權限範圍 +2. 在 Logto OAuth 連接器中啟用 **持久 API 存取權杖儲存**。Logto 會將存取權杖 (Access token) 安全儲存在 Secret Vault。 +3. 對於**標準** OAuth/OIDC 身分提供者，必須包含 `offline_access` 權限範圍以取得重新整理權杖 (Refresh token)，避免重複要求使用者同意。 + +:::warning +請妥善保管你的 client secret，切勿在前端程式碼中暴露。如果發現外洩，請立即在身分提供者的應用程式設定中產生新金鑰。 +::: + +## 使用 OAuth 連接器 \{#utilize-the-oauth-connector} + +建立 OAuth 連接器並連接到你的身分提供者後，你可以將其整合到終端使用者流程中。請依需求選擇下列方式： + +### 啟用社交登入按鈕 \{#enable-social-sign-in-button} + +1. 在 Logto Console 前往 登入體驗 > 註冊與登入。 +2. 在 **社交登入** 區段新增 OAuth 連接器，讓使用者可透過你的身分提供者驗證。 + +進一步瞭解 [社交登入體驗](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 連結或解除連結社交帳號 \{#link-or-unlink-a-social-account} + +使用 Account API 在你的應用程式中建立自訂帳號中心，讓已登入使用者連結或解除連結社交帳號。[參考 Account API 教學](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以僅啟用 OAuth 連接器作為帳號連結與 API 存取用途，而不必啟用社交登入。 +::: + +### 存取身分提供者 API 並執行操作 \{#access-identity-provider-apis-and-perform-actions} + +你的應用程式可從 Secret Vault 取得已儲存的存取權杖 (Access token)，以呼叫身分提供者 API 並自動化後端任務。具體能力取決於你的身分提供者及你申請的權限範圍 (Scopes)。請參閱相關指南以瞭解如何取得儲存的權杖進行 API 存取。 + +## 管理使用者的社交身分 \{#manage-user-s-social-identity} + +使用者連結社交帳號後，管理員可在 Logto Console 管理該連線： + +1. 前往 Logto console > 使用者管理 並開啟該使用者的個人資料頁。 +2. 在 **社交連線** 區塊找到身分提供者項目並點擊 **管理**。 +3. 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。 + +:::note +部分身分提供者回傳的存取權杖 (Access token) 回應不包含具體權限範圍 (Scopes) 資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所請求的權限範圍，你的應用程式在存取 OAuth API 時就會擁有相應權限。 +::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx index 5f6192edba4..90d1ca81021 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/README.mdx @@ -1,8 +1,8 @@ --- slug: /integrations/oidc -sidebar_label: OIDC (社交) +sidebar_label: OIDC（社交） sidebar_custom_props: - description: OpenID Connect 1.0 是一個簡單的身分層，建立在 OAuth 2.0 協議之上。 + description: OpenID Connect 1.0 是建立在 OAuth 2.0 協議之上的簡單身分層。 tutorial_name: OIDC tutorial_config_name: Standard OIDC app --- @@ -11,19 +11,29 @@ import GuideTip from '../../fragments/_guide-tip.mdx'; import Integration from './_integration.mdx'; -# 設定 OpenID Connect (OIDC) 社交登入 +# 設定 OpenID Connect (OIDC) 社交登入 (Set up social login with OpenID Connect (OIDC)) -Logto 的 OpenID Connect (OIDC) 協議官方連接器。 +官方 Logto OpenID Connect (OIDC) 協議連接器。 ## 開始使用 \{#get-started} -OIDC 連接器使 Logto 能夠連接到支持 OIDC 協議的任意社交身分提供者。 +OIDC 連接器讓 Logto 能連接任何支援 OIDC 協議的社交身分提供者。使用 OIDC 連接器，你的應用程式可以： + +- 新增社交登入按鈕 +- 將使用者帳號與社交身分連結 +- 從社交提供者同步使用者個人資料資訊 +- 透過 Logto Secret Vault 安全儲存權杖，存取第三方 API 以自動化任務（例如：編輯 Google 文件、管理應用程式中的行事曆事件） + +要設定這些驗證 (Authentication) 功能，請先在 Logto 建立 OIDC 連接器： + +1. 前往 Logto 控制台 > 連接器 > 社交連接器。 +2. 點擊 **新增社交連接器**，選擇 **OIDC**，點擊 **下一步**，並依照分步教學完成整合。 :::note -OIDC 連接器是 Logto 中一種特殊的連接器，你可以新增一些基於 OIDC 的連接器。 +OIDC 連接器是 Logto 中一種特殊的連接器，你可以新增多個基於 OIDC 協議的連接器。 ::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx index f89480f271b..1f0ca752966 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/social/oidc/_integration.mdx @@ -1,51 +1,51 @@ ## 建立你的 OIDC 應用程式 \{#create-your-oidc-app} -當你打開此頁面時，我們相信你已經知道要連接哪個社交身分提供者。首先要確認的是該身分提供者是否支援 OIDC 協議，這是配置有效連接器的前提條件。然後，按照身分提供者的指示註冊並建立相關的 OIDC 授權應用程式。 +當你看到這個頁面時，我們相信你已經知道要連接哪個社交身分提供者。首先，請確認該身分提供者支援 OIDC 協議，這是設定有效連接器的前提。然後，依照身分提供者的指引註冊並建立 OIDC 授權所需的相關應用程式。 -## 配置你的連接器 \{#configure-your-connector} +## 設定你的連接器 \{#configure-your-connector} -出於安全考量，我們僅支援「Authorization Code」授權類型，這非常適合 Logto 的場景。 +基於安全考量，我們**僅支援**「授權碼（Authorization Code）」授權類型，這也完全符合 Logto 的使用情境。 -`clientId` 和 `clientSecret` 可以在你的 OIDC 應用程式詳細資訊頁面找到。 +`clientId` 和 `clientSecret` 可以在你的 OIDC 應用程式詳細頁面找到。 -_clientId_：客戶端 ID 是在註冊時用來識別客戶端應用程式的唯一識別符。授權伺服器使用此 ID 驗證客戶端應用程式的身分，並將任何授權的存取權杖與該特定客戶端應用程式關聯。 +_clientId_：client ID 是用於在註冊時識別用戶端應用程式的唯一識別碼。授權伺服器會用這個 ID 來驗證用戶端應用程式的身分，並將任何授權的存取權杖（Access token）與該特定用戶端應用程式關聯。 -_clientSecret_：客戶端密鑰是在註冊時由授權伺服器發給客戶端應用程式的機密金鑰。客戶端應用程式使用此密鑰在請求存取權杖時向授權伺服器進行驗證。客戶端密鑰被視為機密資訊，應始終保持安全。 +_clientSecret_：client secret 是授權伺服器在註冊時發給用戶端應用程式的機密金鑰。用戶端應用程式在請求存取權杖（Access token）時，會用這個金鑰向授權伺服器驗證自身身分。client secret 屬於機密資訊，必須隨時妥善保管。 -_tokenEndpointAuthMethod_：權杖端點驗證方法由客戶端應用程式用來在請求存取權杖時向授權伺服器進行驗證。要發現支援的方法，請查閱 OAuth 2.0 服務提供者的 OpenID Connect 發現端點中的 `token_endpoint_auth_methods_supported` 欄位，或參考 OAuth 2.0 服務提供者提供的相關文件。 +_tokenEndpointAuthMethod_：權杖端點驗證方法（token endpoint authentication method）是用戶端應用程式在請求存取權杖（Access token）時，向授權伺服器驗證自身身分所用的方法。請參考 OAuth 2.0 服務提供者的 OpenID Connect 探索端點（discovery endpoint）中的 `token_endpoint_auth_methods_supported` 欄位，或查閱相關文件以瞭解支援的方法。 -_clientSecretJwtSigningAlgorithm (可選)_：僅在 `tokenEndpointAuthMethod` 為 `client_secret_jwt` 時需要。客戶端密鑰 JWT 簽名算法由客戶端應用程式用來簽署在權杖請求期間發送給授權伺服器的 JWT。 +_clientSecretJwtSigningAlgorithm（選填）_：僅當 `tokenEndpointAuthMethod` 為 `client_secret_jwt` 時需要。client secret JWT 簽章演算法用於用戶端應用程式在權杖請求（Token request）時簽署傳送給授權伺服器的 JWT。 -_scope_：權限範圍參數用來指定客戶端應用程式請求存取的資源和權限集合。權限範圍參數通常定義為一個以空格分隔的值列表，代表特定的權限。例如，權限範圍值「read write」可能表示客戶端應用程式請求對使用者資料的讀取和寫入存取。 +_scope_：scope 參數用於指定用戶端應用程式請求存取的資源與權限範圍（Scopes）。scope 通常是一串以空格分隔的值，代表特定權限。例如，scope 設為 "read write" 可能表示用戶端應用程式請求讀寫使用者資料的權限。 -你應該能在社交供應商的文件中找到 `authorizationEndpoint`、`tokenEndpoint`、`jwksUri` 和 `issuer` 作為 OpenID 提供者的配置信息。 +你應該能在 OpenID Provider 的設定資訊中找到 `authorizationEndpoint`、`tokenEndpoint`、`jwksUri` 和 `issuer`。這些資訊通常可在社交平台的文件中查到。 -_authenticationEndpoint_：此端點用來啟動驗證過程。驗證過程通常涉及使用者登入並授權客戶端應用程式存取其資源。 +_authenticationEndpoint_：這個端點用於啟動驗證流程。驗證流程通常包含使用者登入並授權用戶端應用程式存取其資源。 -_tokenEndpoint_：此端點由客戶端應用程式用來獲取可用於存取請求資源的 ID 權杖。客戶端應用程式通常向權杖端點發送帶有授權類型和授權碼的請求以接收 ID 權杖。 +_tokenEndpoint_：這個端點讓用戶端應用程式取得 ID 權杖（ID token），以便存取所請求的資源。用戶端應用程式通常會帶著授權碼（authorization code）和授權類型（grant type）向 token endpoint 發送請求，以取得 ID 權杖。 -_jwksUri_：這是可以獲取社交身分提供者（簡稱 IdP）JSON Web Key Set (JWKS) 的 URL 端點。JWKS 是一組加密金鑰，IdP 用來簽署和驗證在驗證過程中發出的 JSON Web Tokens (JWTs)。`jwksUri` 由依賴方 (RP) 用來獲取 IdP 用來簽署 JWT 的公鑰，以便 RP 可以驗證從 IdP 接收到的 JWT 的真實性和完整性。 +_jwksUri_：這是社交身分提供者（IdP, Identity provider）的 JSON Web Key Set（JWKS）網址端點。JWKS 是一組加密金鑰，IdP 用來簽署與驗證驗證流程中發出的 JSON Web Token（JWT）。`jwksUri` 讓信賴方（RP, Relying Party）取得 IdP 用來簽署 JWT 的公開金鑰，以驗證從 IdP 收到的 JWT 的真實性與完整性。 -_issuer_：這是 IdP 的唯一識別符，由 RP 用來驗證從 IdP 接收到的 JWT。它作為 `iss` [宣告 (claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4) 包含在 JWT 中（ID 權杖始終是 JWT）。簽發者值應與 IdP 的授權伺服器的 URL 匹配，並且應為 RP 信任的 URI。當 RP 接收到 JWT 時，它會檢查 `iss` 宣告以確保它是由受信任的 IdP 簽發的，並且該 JWT 是用於 RP 的。 +_issuer_：這是 IdP 的唯一識別碼，RP 會用來驗證從 IdP 收到的 JWT。它會以 `iss` [宣告 (Claim)](https://www.rfc-editor.org/rfc/rfc7519#section-4) 包含在 JWT 中（ID 權杖永遠是 JWT）。issuer 的值應與 IdP 授權伺服器的 URL 相符，且必須是 RP 信任的 URI。RP 收到 JWT 時，會檢查 `iss` 宣告，確保它是由信任的 IdP 簽發，且該 JWT 是給 RP 使用的。 -`jwksUri` 和 `issuer` 一起提供了一種安全機制，讓 RP 在驗證過程中驗證終端使用者的身分。通過使用從 `jwksUri` 獲得的公鑰，RP 可以驗證 IdP 簽發的 JWT 的真實性和完整性。簽發者值確保 RP 僅接受由受信任的 IdP 簽發的 JWT，並且這些 JWT 是用於 RP 的。 +`jwksUri` 和 `issuer` 結合起來，為 RP 在驗證流程中驗證終端使用者身分提供安全機制。RP 透過 `jwksUri` 取得公開金鑰，驗證 IdP 發出的 JWT 的真實性與完整性；issuer 則確保 RP 只接受由信任的 IdP 簽發、且專為 RP 使用的 JWT。 -由於驗證請求始終是必需的，因此提供了 `authRequestOptionalConfig` 來包裝所有可選配置，你可以在 [OIDC 驗證請求](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) 中找到詳細資訊。你可能還會發現此配置中缺少 `nonce`。由於 `nonce` 應在每個請求中相同，我們將 `nonce` 的生成放在程式碼實現中。所以不用擔心！前面提到的 `jwksUri` 和 `issuer` 也包含在 `idTokenVerificationConfig` 中。 +由於每次都需要驗證請求（Authentication request），我們提供 `authRequestOptionalConfig` 來包裝所有選填設定，詳細內容請參考 [OIDC 驗證請求 (Authentication Request)](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)。你可能會發現這裡沒有 `nonce`，因為 `nonce` 每次請求都要唯一，我們將其產生邏輯放在程式碼實作中，所以不用擔心！前述的 `jwksUri` 和 `issuer` 也包含在 `idTokenVerificationConfig` 中。 -你可能會好奇為什麼標準 OIDC 協議支援隱式和混合流，而 Logto 連接器僅支援授權流。已確定隱式和混合流比授權流安全性較低。由於 Logto 專注於安全性，儘管其便利性稍差，但它僅支援授權流以提供給使用者最高級別的安全性。 +你可能會好奇，為什麼標準 OIDC 協議支援 implicit 與 hybrid 流程，但 Logto 連接器只支援授權流程（Authorization flow）。這是因為 implicit 與 hybrid 流程的安全性較低。Logto 著重安全性，因此僅支援授權流程，為用戶提供最高安全等級，雖然便利性略低。 -`responseType` 和 `grantType` 在「Authorization Code」流中只能是固定值，因此我們將它們設為可選，並會自動填入預設值。 +`responseType` 和 `grantType` 在「授權碼（Authorization Code）」流程下只能是固定值，因此我們將其設為選填，預設值會自動填入。 :::note -對於所有流類型，我們提供了一個可選的 `customConfig` 鍵來放置你的自訂參數。 -每個社交身分提供者可能在 OIDC 標準協議上有自己的變體。如果你想要的社交身分提供者嚴格遵循 OIDC 標準協議，那麼你不需要關心 `customConfig`。 +針對所有流程類型，我們提供選填的 `customConfig` 欄位讓你放自訂參數。 +每個社交身分提供者對 OIDC 標準協議可能有自己的變體。如果你的目標身分提供者嚴格遵循 OIDC 標準協議，則不需要特別處理 `customConfig`。 ::: -## 配置類型 \{#config-types} +## 設定類型 \{#config-types} -| 名稱 | 類型 | 必需 | +| 名稱 | 類型 | 必填 | | ------------------------- | ------------------------- | ---- | | scope | string | 是 | | clientId | string | 是 | @@ -56,7 +56,7 @@ _issuer_：這是 IdP 的唯一識別符，由 RP 用來驗證從 IdP 接收到 | authRequestOptionalConfig | AuthRequestOptionalConfig | 否 | | customConfig | Record\ | 否 | -| AuthRequestOptionalConfig 屬性 | 類型 | 必需 | +| AuthRequestOptionalConfig 屬性 | 類型 | 必填 | | ------------------------------ | ------ | ---- | | responseType | string | 否 | | tokenEndpoint | string | 否 | @@ -69,7 +69,7 @@ _issuer_：這是 IdP 的唯一識別符，由 RP 用來驗證從 IdP 接收到 | loginHint | string | 否 | | acrValues | string | 否 | -| IdTokenVerificationConfig 屬性 | 類型 | 必需 | +| IdTokenVerificationConfig 屬性 | 類型 | 必填 | | ------------------------------ | ---------------------------------- | ---- | | jwksUri | string | 是 | | issuer | string \| string[] | 否 | @@ -82,4 +82,70 @@ _issuer_：這是 IdP 的唯一識別符，由 RP 用來驗證從 IdP 接收到 | subject | string | 否 | | typ | string | 否 | -查看 [這裡](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) 以獲取有關 `IdTokenVerificationConfig` 的更多詳細資訊。 +更多 `IdTokenVerificationConfig` 詳細說明請參考 [這裡](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md)。 + +## 一般設定 \{#general-settings} + +以下是一些不會阻礙你連接身分提供者，但可能影響終端使用者驗證體驗的一般設定。 + +### 社交按鈕名稱與 Logo \{#social-button-name-and-logo} + +如果你希望在登入頁面顯示社交按鈕，可以設定社交身分提供者的**名稱**與**Logo**（深色模式與淺色模式）。這有助於使用者辨識社交登入選項。 + +### 身分提供者名稱 \{#identity-provider-name} + +每個社交連接器都有唯一的身分提供者（IdP, Identity Provider）名稱，用來區分使用者身分。常見連接器會使用固定的 IdP 名稱，自訂連接器則需填入唯一值。詳情請參閱 [IdP 名稱說明](https://docs.logto.io/connectors/connector-data-structure#target-identity-provider-name)。 + +### 同步個人資料資訊 \{#sync-profile-information} + +在 OIDC 連接器中，你可以設定同步個人資料（如使用者名稱與頭像）的政策。可選擇： + +- **僅註冊時同步**：使用者首次登入時會取得一次個人資料。 +- **每次登入時皆同步**：每次使用者登入時都會更新個人資料。 + +### 儲存權杖以存取第三方 API（選填） \{#store-tokens-to-access-third-party-apis-optional} + +如果你希望存取身分提供者的 API 並以使用者授權執行操作（無論是社交登入或帳號綁定），Logto 需要取得特定 API 權限範圍（Scopes）並儲存權杖（Tokens）。 + +1. 依上述說明在 **scope** 欄位加入所需權限範圍 +2. 在 Logto OIDC 連接器中啟用 **持久化 API 存取權杖儲存**。Logto 會將存取權杖（Access token）安全地儲存在 Secret Vault。 +3. 對於**標準** OAuth/OIDC 身分提供者，必須包含 `offline_access` 權限範圍以取得重新整理權杖（Refresh token），避免重複要求使用者同意。 + +:::warning +請妥善保管你的 client secret，切勿在前端程式碼中暴露。如果發現外洩，請立即在身分提供者的應用程式設定中產生新金鑰。 +::: + +## 使用 OIDC 連接器 \{#utilize-the-oidc-connector} + +當你建立好 OIDC 連接器並連接到身分提供者後，即可將其整合進終端使用者流程。請依需求選擇下列方式： + +### 啟用社交登入按鈕 \{#enable-social-sign-in-button} + +1. 在 Logto Console 前往 登入體驗 > 註冊與登入。 +2. 在 **社交登入** 區塊新增 OIDC 連接器，讓使用者能以你的身分提供者驗證。 + +進一步瞭解 [社交登入體驗](https://docs.logto.io/end-user-flows/sign-up-and-sign-in/social-sign-in)。 + +### 綁定或解除綁定社交帳號 \{#link-or-unlink-a-social-account} + +使用 Account API 在你的應用程式中建立自訂帳號中心，讓已登入使用者綁定或解除綁定社交帳號。[參考 Account API 教學](https://docs.logto.io/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +:::tip +你可以只啟用 OIDC 連接器作為帳號綁定與 API 存取用途，而不啟用社交登入。 +::: + +### 存取身分提供者 API 並執行操作 \{#access-identity-provider-apis-and-perform-actions} + +你的應用程式可以從 Secret Vault 取得儲存的存取權杖（Access token），呼叫身分提供者 API 並自動化後端任務。具體能力取決於你的身分提供者與你申請的權限範圍。請參考相關教學以瞭解如何取得儲存的權杖進行 API 存取。 + +## 管理使用者的社交身分 \{#manage-user-s-social-identity} + +當使用者綁定社交帳號後，管理員可在 Logto Console 管理該連線： + +1. 前往 Logto console > 使用者管理 並開啟該使用者的個人資料。 +2. 在 **社交連線** 區塊找到身分提供者項目並點擊 **管理**。 +3. 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資料資訊，以及檢查存取權杖狀態。 + +:::note +部分身分提供者的存取權杖（Access token）回應不包含具體權限範圍（Scopes）資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所請求的權限範圍，你的應用程式在存取 OIDC API 時就會擁有相應權限。 +::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx index c74e643eaee..d2cb27ca73a 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/README.mdx @@ -2,7 +2,7 @@ slug: /integrations/google-workspace sidebar_label: Google Workspace sidebar_custom_props: - description: 在 Google 生態系統中統一且安全地管理使用者存取。 + description: 在 Google 生態系統中統一且安全地管理使用者存取權限 (Unified and secure management of user access within the Google ecosystem)。 logoFilename: 'google.svg' tutorial_name: Google Workspace enterprise SSO tutorial_config_name: Google Cloud Platform @@ -16,18 +16,19 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -# 設定 Google Workspace 單一登入 (SSO) +# 設定 Google Workspace 單一登入 (SSO, Single Sign-On) -只需最少的配置工作，此連接器即可與 Microsoft Entra ID 整合以實現企業級單一登入 (SSO)。 +只需極少設定，即可透過此連接器整合 Microsoft Entra ID 以實現企業級單一登入 (SSO)。 -## 步驟 1：在 Google Cloud Platform 上建立新專案 \{#step-1-create-a-new-project-on-google-cloud-platform} +## 步驟 1：在 Google Cloud Platform 建立新專案 \{#step-1-create-a-new-project-on-google-cloud-platform} -## 步驟 2：為你的應用程式配置使用者授權頁面 \{#step-2-config-the-consent-screen-for-your-application} +## 步驟 2：為你的應用程式設定使用者授權頁面 (Consent screen) \{#step-2-config-the-consent-screen-for-your-application} @@ -35,14 +36,18 @@ import Step6 from './_step-6.mdx'; -## 步驟 4：使用客戶端憑證設定 Logto 連接器 \{#step-4-set-up-logto-connector-with-the-client-credentials} +## 步驟 4：使用用戶端憑證設定 Logto 連接器 \{#step-4-set-up-logto-connector-with-the-client-credentials} -## 步驟 5：額外的權限範圍 (Scopes)（可選）\{#step-5-additional-scopes-optional} +## 步驟 5：額外權限範圍 (選填) \{#step-5-additional-scopes-optional} -## 步驟 6：設定電子郵件網域並啟用 SSO 連接器 \{#step-6-set-email-domains-and-enable-the-sso-connector} +## 步驟 6：儲存權杖以存取 Google API（選填） \{#step-6-store-tokens-to-access-google-apis-optional} + +## 步驟 7：設定電子郵件網域並啟用 SSO 連接器 \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx index 7592e3d8306..8473940aa86 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_integration.mdx @@ -4,12 +4,13 @@ import Step3 from './_step-3.mdx'; import Step4 from './_step-4.mdx'; import Step5 from './_step-5.mdx'; import Step6 from './_step-6.mdx'; +import Step7 from './_step-7.mdx'; -### 步驟 1：在 Google Cloud Platform 上建立新專案 \{#step-1-create-a-new-project-on-google-cloud-platform} +### 步驟 1：在 Google Cloud Platform 建立新專案 \{#step-1-create-a-new-project-on-google-cloud-platform} -### 步驟 2：為你的應用程式配置使用者授權頁面 \{#step-2-config-the-consent-screen-for-your-application} +### 步驟 2：為你的應用程式設定使用者授權頁面 (Consent screen) \{#step-2-config-the-consent-screen-for-your-application} @@ -17,14 +18,18 @@ import Step6 from './_step-6.mdx'; -### 步驟 4：使用客戶端憑證設定 Logto 連接器 \{#step-4-set-up-logto-connector-with-the-client-credentials} +### 步驟 4：使用用戶端憑證設定 Logto 連接器 (Connector) \{#step-4-set-up-logto-connector-with-the-client-credentials} -### 步驟 5：額外的權限範圍 (Scopes)（可選）\{#step-5-additional-scopes-optional} +### 步驟 5：額外權限範圍 (Scopes)（選填）\{#step-5-additional-scopes-optional} -### 步驟 6：設定電子郵件網域並啟用 SSO 連接器 \{#step-6-set-email-domains-and-enable-the-sso-connector} +### 步驟 6：儲存權杖 (Tokens) 以存取 Google API（選填） \{#step-6-store-tokens-to-access-google-apis-optional} + +### 步驟 7：設定電子郵件網域並啟用 SSO 連接器 (Connector) \{#step-7-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx index 61e7a17e519..82b937967cd 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-5.mdx @@ -1,3 +1,22 @@ -使用 `Scope` 欄位為你的 OAuth 請求新增額外的權限範圍 (Scopes)。這將允許你從 Google OAuth 伺服器請求更多資訊。更多資訊請參閱 [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) 文件。 +Scopes（權限範圍）定義你的應用程式向使用者請求的權限，並控制你的應用程式能從他們的 Google Workspace 帳戶存取哪些資料。請求 Google 權限需要雙方設定： -無論自訂權限範圍 (Scopes) 設定如何，Logto 將始終向 IdP 傳送 `openid`、`profile` 和 `email` 權限範圍 (Scopes)。這是為了確保 Logto 能夠正確檢索使用者的身分資訊和電子郵件地址。 +**在 Google Cloud Console：** + +1. 前往 **APIs & Services > OAuth consent screen > Scopes**。 +2. 點擊 **Add or Remove Scopes**，僅選擇你的應用程式所需的 scopes（權限範圍）： + - 驗證 (Authentication)（必填）： + - `https://www.googleapis.com/auth/userinfo.email` + - `https://www.googleapis.com/auth/userinfo.profile` + - `openid` + - API 存取（選填）：根據應用程式需求新增額外的 scopes（例如 Drive、Calendar、YouTube）。可瀏覽 [Google API Library](https://console.cloud.google.com/apis/library) 以查找可用服務。如果你的應用程式需要超出基本權限的 Google API 存取，請先在 Google API Library 啟用應用程式將使用的特定 API（如 Google Drive API、Gmail API、Calendar API）。 +3. 點擊 **Update** 以確認選擇。 +4. 點擊 **Save and Continue** 以套用變更。 + +**在 Logto Google Workspace 連接器 (Connector)：** + +1. Logto 會自動包含 `openid`、`profile` 和 `email` scopes（權限範圍），以取得基本使用者身分資訊。如果你只需要基本使用者資訊，可以將 `Scopes` 欄位留空。 +2. 若需向 Google 請求更多資料，請在 `Scopes` 欄位中以空格分隔新增額外的 scopes（權限範圍）。請使用完整的 scope URL，例如：`https://www.googleapis.com/auth/calendar.readonly` + +:::tip +如果你的應用程式請求這些 scopes（權限範圍）以存取 Google API 並執行操作，請務必在 Logto Google 連接器 (Connector) 中啟用 **Store tokens for persistent API access**（儲存權杖以持久存取 API）。詳情請參閱下一節。 +::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx index 47818d6fa02..5a067db35e9 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-6.mdx @@ -1,5 +1,9 @@ -在 Logto 的連接器 `SSO 體驗` 標籤中提供你組織的 `電子郵件網域`。這將啟用 SSO 連接器作為這些使用者的驗證 (Authentication) 方法。 +如果你想存取 [Google APIs](https://console.cloud.google.com/apis/library) 並在使用者授權下執行操作，Logto 需要取得特定的 API 權限範圍 (Scopes) 並儲存權杖 (Tokens)。 -擁有指定網域電子郵件地址的使用者將被重定向，使用你的 SSO 連接器作為他們唯一的驗證 (Authentication) 方法。 +1. 在 Google Cloud Console 的 OAuth 使用者授權頁面 (Consent screen) 設定及 Logto Google 連接器 (Connector) 中新增所需的權限範圍 (Scopes)。 +2. 在 Logto Google 連接器中啟用 **儲存權杖以持續存取 API（Store tokens for persistent API access）**。Logto 會將 Google 存取權杖 (Access tokens) 和重新整理權杖 (Refresh tokens) 安全地儲存在 Secret Vault。 +3. 為確保能取得重新整理權杖 (Refresh tokens)，請在 Logto Google 連接器中啟用 **離線存取（Offline Access）**。 -如需有關 Google Workspace SSO 連接器的更多資訊，請查看 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect)。 +:::warning +你不需要在 Logto 的 `Scope` 欄位中加入 `offline_access` —— 這麼做可能會導致錯誤。Google 在啟用離線存取時會自動使用 `access_type=offline`。 +::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx new file mode 100644 index 00000000000..c4f97150727 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/google-workspace/_step-7.mdx @@ -0,0 +1,5 @@ +在 Logto 的連接器 `SSO 體驗 (SSO experience)` 分頁中提供你組織的 `email domains`。這將使 SSO 連接器成為這些使用者的驗證 (Authentication) 方法。 + +擁有指定網域電子郵件地址的使用者，將會被導向僅能使用你的 SSO 連接器進行驗證 (Authentication)。 + +如需更多有關 Google Workspace SSO 連接器的資訊，請參閱 [Google OpenID Connector](https://developers.google.com/identity/openid-connect/openid-connect)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx index 91dc06f18bf..b921bdc7a40 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/README.mdx @@ -1,8 +1,8 @@ --- slug: /integrations/oidc-sso -sidebar_label: OIDC (企業級) +sidebar_label: OIDC（企業級） sidebar_custom_props: - description: 建立在 OAuth 2.0 之上的現代協議，用於網頁和行動應用程式的身分驗證。 + description: 建立於 OAuth 2.0 之上的現代協議，用於網頁與行動應用程式的身分驗證。 logoFilename: 'oidc.svg' tutorial_name: OIDC enterprise SSO tutorial_config_name: OIDC application on your IdP @@ -13,10 +13,12 @@ import GuideTip from '../../fragments/_sso_guide_tip.mdx'; import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; # 設定 OpenID Connect (OIDC) 單一登入 (SSO) -透過最少的配置工作，此連接器允許與任何基於 OIDC 的身分提供者 (IdP) 整合。 +只需極少設定，即可透過此連接器整合任何基於 OIDC 的身分提供者 (IdP, Identity Provider)。 @@ -24,10 +26,18 @@ import Step3 from './_step-3.mdx'; -## 步驟 2：在 Logto 上配置 OIDC 單一登入 (SSO) \{#step-2-configure-oidc-sso-on-logto} +## 步驟 2：在 Logto 上設定 OIDC 單一登入 (SSO) \{#step-2-configure-oidc-sso-on-logto} -## 步驟 3：設定電子郵件網域並啟用 SSO 連接器 \{#step-3-set-email-domains-and-enable-the-sso-connector} +## 步驟 3：設定權限範圍 (Scopes)（選填） \{#step-3-configure-scopes-optional} + +## 步驟 4：儲存權杖以存取第三方 API（選填） \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## 步驟 5：設定電子郵件網域並啟用 SSO 連接器 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx index bfc8e3151e7..f6e086da7a4 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_integration.mdx @@ -1,15 +1,25 @@ import Step1 from './_step-1.mdx'; import Step2 from './_step-2.mdx'; import Step3 from './_step-3.mdx'; +import Step4 from './_step-4.mdx'; +import Step5 from './_step-5.mdx'; -### 步驟 1：在你的 IdP 上建立 OIDC 應用程式 \{#step-1-create-an-oidc-application-on-your-idp} +### 步驟 1：在你的身分提供者 (IdP, Identity Provider) 上建立 OIDC 應用程式 \{#step-1-create-an-oidc-application-on-your-idp} -### 步驟 2：在 Logto 上配置 OIDC 單一登入 (SSO) \{#step-2-configure-oidc-sso-on-logto} +### 步驟 2：在 Logto 上設定 OIDC 單一登入 (SSO, Single Sign-On) \{#step-2-configure-oidc-sso-on-logto} -### 步驟 3：設定電子郵件網域並啟用 SSO 連接器 \{#step-3-set-email-domains-and-enable-the-sso-connector} +## 步驟 3：設定權限範圍 (Scopes)（選填） \{#step-3-configure-scopes-optional} + +## 步驟 4：儲存權杖以存取第三方 API（選填） \{#step-4-store-tokens-to-access-third-party-apis-optional} + + + +## 步驟 5：設定電子郵件網域並啟用 SSO 連接器 \{#step-5-set-email-domains-and-enable-the-sso-connector} + + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx index 7f8779dc7f4..0fd2ea10ae6 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-2.mdx @@ -1,10 +1,7 @@ -在 IdP 端成功建立 OIDC 應用程式後，你需要將 IdP 配置提供給 Logto。導航至 `Connection` 標籤，並填寫以下配置： +在 IdP 端成功建立 OIDC 應用程式後，你需要將 IdP 的相關設定資訊回填至 Logto。請前往 `Connection` 分頁，並填寫以下設定： -- **Client ID**：由 IdP 分配給你的 OIDC 應用程式的唯一識別符。Logto 使用此識別符在 OIDC 流程中識別和驗證應用程式。 -- **Client Secret**：在 Logto 和 IdP 之間共享的機密密碼。此密碼用於驗證 OIDC 應用程式並保護 Logto 與 IdP 之間的通信。 -- **簽發者 (Issuer)**：簽發者 URL，是 IdP 的唯一識別符，指定 OIDC 身分提供者 (IdP) 的位置。這是 OIDC 配置中的關鍵部分，因為它幫助 Logto 發現必要的端點。 - 為了簡化配置過程，Logto 將自動獲取所需的 OIDC 端點和配置。這是通過利用你提供的簽發者並調用 IdP 的 OIDC 發現端點來完成的。確保簽發者端點有效且配置準確，以便 Logto 正確檢索所需信息是至關重要的。 - 成功獲取請求後，你應該能在簽發者部分看到解析後的 IdP 配置。 -- **權限範圍 (Scope)**：由空格分隔的字串列表，定義 Logto 在 OIDC 驗證過程中請求的所需權限或存取級別。權限範圍參數允許你指定 Logto 從 IdP 請求哪些信息和存取權限。 - 權限範圍參數是可選的。無論自訂權限範圍設置如何，Logto 將始終向 IdP 發送 `openid`、`profile` 和 `email` 權限範圍。 - 這是為了確保 Logto 能夠正確從 IdP 檢索使用者的身分信息和電子郵件地址。你可以在權限範圍參數中添加其他權限範圍，以請求更多來自 IdP 的信息。 +- **Client ID**：由 IdP 指派給你的 OIDC 應用程式的唯一識別碼。Logto 會利用此識別碼在 OIDC 流程中識別並驗證應用程式身分。 +- **Client Secret**：Logto 與 IdP 之間共用的機密金鑰。此金鑰用於驗證 OIDC 應用程式，並保障 Logto 與 IdP 之間的通訊安全。 +- **簽發者 (Issuer)**：簽發者 URL，是 IdP 的唯一識別符，指定 OIDC 身分提供者的位置。這是 OIDC 設定中極為重要的一環，協助 Logto 發現所需的端點。 + 為了讓設定流程更簡便，Logto 會自動擷取所需的 OIDC 端點與設定。這是透過你所提供的簽發者 (Issuer) 進行，並呼叫 IdP 的 OIDC 探索端點 (discover endpoints) 來完成。請務必確保簽發者端點正確有效，才能讓 Logto 正確取得所需資訊。 + 擷取成功後，你應該可以在 issuers 區段看到解析後的 IdP 設定資訊。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx index 12a42b5a118..406ebbec5a0 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-3.mdx @@ -1,3 +1,14 @@ -在 Logto 的連接器 `SSO 體驗` 標籤中提供你組織的 `電子郵件網域`。這將啟用 SSO 連接器作為這些使用者的驗證 (Authentication) 方法。 +權限範圍 (Scopes) 定義了你的應用程式向使用者請求哪些權限，並控制你的應用程式能從他們的企業帳號存取哪些資料。 -擁有指定網域電子郵件地址的使用者將被重定向，使用你的 SSO 連接器作為他們唯一的驗證 (Authentication) 方法。 +設定權限範圍 (Scopes) 需要雙方配置： + +1. **你的身分提供者 (IdP, Identity Provider)**：在 IdP 控制台設定哪些權限允許授權 + - 有些 IdP 預設啟用所有公開權限範圍（無需額外操作） + - 其他則需要你明確授予權限 +2. **Logto 企業連接器 (enterprise connector)**：在 Logto OIDC 企業連接器設定 > `Scopes` 欄位中指定驗證時要請求哪些權限範圍。 + - Logto 無論你的自訂權限範圍設定為何，始終會包含 `openid`、`profile` 和 `email` 權限範圍，以取得基本使用者身分資訊。 + - 你可以額外新增其他權限範圍（以空格分隔），以向 IdP 請求更多資訊。 + +:::tip +如果你的應用程式需要使用這些權限範圍存取 API，請務必在 Logto 企業連接器中啟用 **儲存權杖以持續存取 API（Store tokens for persistent API access）**。詳情請參閱下一節。 +::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx new file mode 100644 index 00000000000..d86328f5184 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-4.mdx @@ -0,0 +1,5 @@ +如果你想存取身分提供者 (Identity Provider, IdP) 的 API 並以使用者授權執行操作，Logto 需要取得特定的 API 權限範圍 (Scopes) 並儲存權杖 (Tokens)。 + +1. 依照上述說明，在 **scope** 欄位中新增所需的權限範圍 (Scopes) +2. 在 Logto OIDC 企業連接器 (Enterprise connector) 中啟用 **為持久性 API 存取儲存權杖 (Store tokens for persistent API access)**。Logto 會將存取權杖 (Access tokens) 安全地儲存在 Secret Vault。 +3. 對於 **標準** OIDC 身分提供者 (Identity provider)，必須包含 `offline_access` 權限範圍 (Scope) 以取得重新整理權杖 (Refresh token)，避免重複要求使用者同意。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx new file mode 100644 index 00000000000..4e5ea495aa0 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrations/sso/oidc/_step-5.mdx @@ -0,0 +1,3 @@ +在 Logto 的連接器 `SSO 使用體驗 (SSO experience)` 分頁中，提供你組織的 `電子郵件網域 (email domains)`。這將使 SSO 連接器成為這些使用者的驗證 (Authentication) 方法。 + +擁有指定網域電子郵件地址的使用者，將會被導向使用你的 SSO 連接器作為唯一的驗證 (Authentication) 方法。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx index c5afffd0f47..7b883598669 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-oss/deployment-and-configuration.mdx @@ -2,40 +2,44 @@ sidebar_position: 2 --- -# 部署與配置 +# 部署與設定 -在上一篇文章中，我們介紹了[快速開始使用 Logto](/logto-oss/get-started-with-oss)的基礎知識。本篇文章將深入探討，重點介紹在生產環境中部署 Logto 的最佳實踐和詳細配置步驟。 +在上一篇文章中，我們介紹了[快速開始使用 Logto](/logto-oss/get-started-with-oss) 的基本流程。本篇將更深入探討，聚焦於生產環境下的最佳實踐與詳細設定步驟。 ## 環境變數 \{#environment-variables} -我們在示範中使用了一組預設的環境變數（`docker-compose.yml`），你應該用自己的變數替換並在多個 Logto 實例中保持一致。 +我們在範例（`docker-compose.yml`）中使用了一組預設產生的環境變數，你應該替換為自己的設定，並在多個 Logto 實例間保持一致。 -你可以直接設置環境變數或將 `.env` 文件放在 Logto 專案的根目錄中。如果你使用 Docker 進行測試，請查看映像生成的 `.env` 文件位於 `/etc/logto`。 +你可以直接設定環境變數，或將 `.env` 檔案放在 Logto 專案根目錄。如果你用 Docker 測試，請查看映像檔在 `/etc/logto` 產生的 `.env`。 -### 基本要素 \{#essentials} +### 基本必填 \{#essentials} - `DB_URL` Logto 資料庫的 [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)。 -- `PORT` Logto 監聽的端口。預設為 `3001`。 -- `ENDPOINT` 你可以為生產環境指定一個自訂域名的 URL（例如 `ENDPOINT=https://logto.domain.com`）。這也會影響 [OIDC 簽發者識別符](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 +- `PORT` Logto 監聽的埠號，預設為 `3001`。 +- `ENDPOINT` 可指定生產環境下自訂網域的 URL（例如：`ENDPOINT=https://logto.domain.com`）。這也會影響 [OIDC 簽發者識別碼 (Issuer Identifier)](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) 的值。 -**啟用管理控制台** +**啟用管理主控台** -- `ADMIN_PORT` Logto 管理控制台監聽的端口。預設為 `3002`。 -- `ADMIN_ENDPOINT` 你可以為生產環境指定一個自訂域名的 URL（例如 `ADMIN_ENDPOINT=https://admin.domain.com`）。這也會影響管理控制台重定向 URI 的值。 +- `ADMIN_PORT` Logto 管理主控台監聽的埠號，預設為 `3002`。 +- `ADMIN_ENDPOINT` 可指定生產環境下自訂網域的 URL（例如：`ADMIN_ENDPOINT=https://admin.domain.com`）。這也會影響管理主控台重導 URI 的值。 -**禁用管理控制台** +**停用管理主控台** -- `ADMIN_DISABLE_LOCALHOST` 設置為 `1` 或 `true` 以關閉管理控制台的端口。如果未設置 `ADMIN_ENDPOINT`，將完全禁用管理控制台。 +- `ADMIN_DISABLE_LOCALHOST` 設為 `1` 或 `true` 可關閉管理主控台的埠號。若未設定 `ADMIN_ENDPOINT`，將完全停用管理主控台。 -有關環境變數的更多詳細資訊，請參閱[配置](/concepts/core-service/configuration/)。 +更多環境變數細節，請參閱[設定](/concepts/core-service/configuration/)。 + +**啟用 Secret Vault** + +- 若要使用 [Secret Vault](/secret-vault)，你需要將 `SECRET_VAULT_KEK` 設為 Key Encryption Key (KEK) 的 base64 編碼字串。這用於加密 Secret Vault 中的 Data Encryption Keys (DEK)。建議使用 AES-256（32 bytes）。範例：`crypto.randomBytes(32).toString('base64')`。 ### HTTPS \{#https} -你可以使用 Node.js 直接提供 HTTPS 服務，或在 Node.js 前設置 HTTPS 代理 / 負載平衡器。詳情請參閱[啟用 HTTPS](/concepts/core-service/configuration/#enabling-https)。 +你可以直接用 Node.js 提供 HTTPS 服務，或在 Node.js 前設置 HTTPS 代理 / 負載平衡器。詳情請參閱[啟用 HTTPS](/concepts/core-service/configuration/#enabling-https)。 ### 反向代理 \{#reverse-proxy} -如果你想在伺服器上使用反向代理，例如 Nginx 或 Apache，你需要在代理傳遞設置中分別映射 3001 和 3002 端口。假設你使用 Nginx，Logto 驗證端點運行在 3001 端口，Logto 管理控制台運行在 3002 端口，請在 nginx.conf 中加入以下配置： +如果你想在伺服器上使用反向代理（如 Nginx 或 Apache），需要在代理設定中分別對應 3001 與 3002 埠。假設你使用 Nginx，Logto 驗證端點運行於 3001 埠，Logto 管理主控台運行於 3002 埠，請在 nginx.conf 中加入以下設定： ``` server { @@ -58,7 +62,7 @@ server { } ``` -然後為你的管理控制台添加類似的配置： +然後為管理主控台加入類似設定： ``` server { @@ -81,23 +85,23 @@ server { } ``` -重新加載 Nginx 配置以應用最新更改： +重新載入 Nginx 設定以套用最新變更： ``` nginx -s reload ``` -一切就緒。打開瀏覽器並訪問 `https://admin.your-domain.com`，你應該能看到 Logto 歡迎頁面。 +一切就緒！打開瀏覽器並造訪 `https://admin.your-domain.com`，你應該能看到 Logto 歡迎頁面。 ## 容器化 \{#containerization} -在生產環境中，你可以使用 Docker 將 Logto 容器化。你可以在專案的根目錄中找到 Dockerfile。如果你想運行多個 Logto 實例，例如在 Kubernetes 集群中部署 Logto，則需要採取一些額外步驟。 +在生產環境中，你可以用 Docker 將 Logto 容器化。專案根目錄有 Dockerfile。如果你想執行多個 Logto 實例，例如在 Kubernetes 叢集部署 Logto，還需額外步驟。 -### 共享連接器資料夾 \{#shared-connectors-folder} +### 共用 connectors 資料夾 \{#shared-connectors-folder} -預設情況下，Logto 會在 `core` 資料夾的根目錄中創建一個 `connectors` 資料夾。我們建議在多個 Logto 實例之間共享該資料夾，你需要將 `packages/core/connectors` 資料夾掛載到容器中，並運行 `npm run cli connector add -- --official` 來部署連接器。 +預設情況下，Logto 會在 `core` 資料夾根目錄建立 `connectors` 資料夾。我們建議多個 Logto 實例間共用此資料夾，你需要將 `packages/core/connectors` 資料夾掛載到容器，並執行 `npm run cli connector add -- --official` 來部署連接器。 -以下是 Kubernetes 的一個最小範例 `deployment`： +以下為 Kubernetes 的最小範例 `deployment`： ```yaml apiVersion: extensions/v1beta1 @@ -130,21 +134,21 @@ spec: mountPath: /etc/logto/packages/core/connectors ``` -在此範例中，我們創建了一個空目錄作為卷並掛載到容器中。然後我們在初始化容器中運行 `npm run cli connector add -- --official` 來下載連接器。最後，每個容器將共享相同的連接器資料夾，其中已包含我們的官方連接器。 +在這個範例中，我們建立一個空目錄作為 volume 並掛載到容器。然後在 init container 執行 `npm run cli connector add -- --official` 下載連接器。最後，每個 container 都會共用同一個已包含官方連接器的 connectors 資料夾。 :::note -這是一個範例 yaml，為了運行 Logto，你需要正確設置環境變數。 +這是範例 yaml，實際執行 Logto 前，請正確設定環境變數。 ::: -在生產環境中，你可以將 "empty dir" 卷替換為持久卷，並以自己的方式完成 "init" 任務，你知道你在做什麼！ +生產環境下，你可以將 "empty dir" volume 換成持久化 volume，並用自己的方式執行 "init" 任務，只要你知道自己在做什麼！ ### 資料庫變更 \{#database-alteration} -與連接器類似，資料庫變更需要在單個實例中運行。你可以使用一個任務來運行變更腳本。 +與連接器類似，資料庫變更需在單一實例執行。你可以用 job 執行變更腳本。 -當變更以非互動方式運行時，`CI=true` 環境變數是必要的。 +當以非互動方式執行變更時，必須設置 `CI=true` 環境變數。 ```yaml apiVersion: batch/v1 @@ -171,4 +175,4 @@ spec: restartPolicy: Never ``` -有關變更命令的詳細資訊，請參閱[資料庫變更](/logto-oss/using-cli/database-alteration/)。 +關於變更指令詳情，請參閱[資料庫變更](/logto-oss/using-cli/database-alteration/)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/secret-vault/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/secret-vault/README.mdx new file mode 100644 index 00000000000..a2e779d8e82 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/secret-vault/README.mdx @@ -0,0 +1,37 @@ +import Connectors from '@site/src/assets/connectors.svg'; + +# Secret Vault + +Logto 的 Secret Vault 設計用於安全儲存敏感的使用者資料——例如存取權杖 (Access tokens)、API 金鑰、通行碼，或任何需要保護的機密資訊。這些秘密通常用於代表使用者存取第三方服務，因此安全儲存至關重要。 + +## 加密機制 \{#encryption-scheme} + +為保護敏感資料，Secret Vault 採用基於 **資料加密金鑰 (DEK, Data Encryption Keys)** 與 **金鑰加密金鑰 (KEK, Key Encryption Keys)** 的強大加密機制。 + +- **每個秘密獨立加密：** 每個秘密都使用其專屬的 DEK 加密，即使某一金鑰遭到洩漏，其他秘密仍然安全。 +- **金鑰包裹 (Key wrapping)：** DEK 本身會被 KEK 加密（或「包裹」），而 KEK 由系統安全管理與儲存。 +- **分層安全：** 這種雙層設計確保即使系統部分遭入侵，攻擊者若無 DEK 與 KEK 皆無法取得秘密。 +- **最小化暴露：** 只有在絕對必要時才會解密秘密，降低意外暴露風險，並符合敏感資料處理最佳實踐。 + +這種分層加密模型為使用者最敏感的憑證與權杖提供強大保護，同時在需要時仍可安全存取。 + +## 秘密類型 \{#secret-types} + +, + }, + }, + ]} +/> + +:::info +目前，聯邦權杖組 (Federated token set) 是唯一內建支援的秘密類型。不過，Secret Vault 的設計可容納任何類型的敏感資訊。如果你需要支援其他秘密類型，請[聯絡我們](https://logto.io/contact)——我們很樂意協助你。 +::: diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx new file mode 100644 index 00000000000..a1ab020f666 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/secret-vault/federated-token-set.mdx @@ -0,0 +1,231 @@ +--- +id: federated-token-set +title: 聯邦權杖集 (Federated token set) +sidebar_label: 聯邦權杖集 (Federated token set) +--- + +import Availability from '@components/Availability'; + + + +聯邦權杖集 (Federated token set) 是儲存在 Logto Secret Vault 的一種密鑰類型，用於安全管理由聯邦第三方身分提供者簽發的存取權杖 (Access token) 與重新整理權杖 (Refresh token)。當使用者透過社交或企業級單一登入 (SSO) 連接器進行驗證時，Logto 會將簽發的權杖儲存在 Vault 中。這些權杖日後可被取出，用於代表使用者存取第三方 API，而無需再次驗證。 + +## 啟用聯邦權杖儲存 \{#enable-federated-token-storage} + +### 社交連接器 \{#social-connectors} + +:::Info +此功能僅適用於支援權杖儲存的連接器。目前支援的連接器包括：[GitHub](/integrations/github)、[Google](/integrations/google)、[Facebook](/integrations/facebook)、[標準 OAuth 2.0](/integrations/oauth2) 以及 [標準 OIDC](/integrations/oidc)。未來將逐步支援更多連接器。 +::: + +1. 前往 Console > Connectors > Social Connectors。 +2. 選擇你要啟用聯邦權杖儲存的社交連接器。 +3. 在「Setting」頁面，啟用 **為持久 API 存取儲存權杖**（Store tokens for persistent API access）選項。 + +### 企業級單一登入 (Enterprise SSO) 連接器 \{#enterprise-sso-connectors} + +:::Info +所有 OIDC 企業級連接器皆支援權杖儲存。 +::: + +1. 前往 Console > Enterprise SSO。 +2. 選擇你要啟用聯邦權杖儲存的企業級 SSO 連接器。 +3. 在「SSO Experience」分頁，啟用 **為持久 API 存取儲存權杖**（Store tokens for persistent API access）選項。 + +請記得儲存你的變更。 + +## 權杖儲存 \{#token-storage} + +啟用聯邦權杖儲存後，Logto 會在使用者透過社交或企業級 SSO 連接器驗證時，自動儲存由聯邦身分提供者簽發的存取權杖 (Access token) 與重新整理權杖 (Refresh token)。包含： + +- [社交登入與註冊](/end-user-flows/sign-up-and-sign-in/social-sign-in) +- [企業級 SSO 登入與註冊](/end-user-flows/enterprise-sso) +- [透過 Account API 連結社交帳號](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection) + +儲存的權杖會綁定於使用者的社交或企業級 SSO 身分，讓他們日後可直接取用權杖以存取 API，無需再次驗證。 + +### 檢查權杖儲存狀態 \{#checking-token-storage-status} + +你可以在 Logto Console 檢查使用者的聯邦權杖儲存狀態： + +1. 前往 Console > Users。 +2. 點擊你想檢查的使用者，進入該使用者詳細頁。 +3. 滾動至 **Connections** 區塊，這裡會列出所有與該使用者關聯的社交與企業級 SSO 連接。 +4. 每個連接項目會顯示權杖狀態標籤，指示該連接是否有儲存權杖。 +5. 點擊連接項目可查看更多細節，包括已儲存的存取權杖 (Access token) 中繼資料與重新整理權杖 (Refresh token) 是否可用（如有）。 + +你也可以透過 Management API 檢查使用者第三方身分與權杖儲存狀態： + +- `GET /api/users/{userId}/identities/{target}?includeTokenSecret=true`：根據指定連接器 target（如 `github`、`google` 等）取得使用者的社交身分與權杖儲存狀態。 +- `GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true`：根據指定 SSO 連接器 ID 取得使用者的企業級 SSO 身分與權杖儲存狀態。 + +### 權杖儲存狀態 \{#token-storage-status} + +- **Active（有效）**：存取權杖已儲存且有效。 +- **Expired（已過期）**：存取權杖已儲存但已過期。若有重新整理權杖，可用於取得新存取權杖。 +- **Inactive（未啟用）**：此連接未儲存存取權杖。可能是使用者尚未透過此連接驗證，或權杖儲存已被刪除。 +- **Not applicable（不適用）**：該連接器不支援權杖儲存。 + +### 權杖中繼資料 \{#token-metadata} + +為確保資料完整性與安全性，所有權杖在儲存至 Secret Vault 前皆經過加密。實際權杖值僅授權的終端使用者可存取。開發者僅能取得權杖集的中繼資料，以便瞭解儲存狀態而不暴露敏感內容。 + +- `createdAt`：首次建立連接並將權杖集儲存至 Secret Vault 的時間戳記。 +- `updatedAt`：權杖集最後一次更新的時間。 + - 若無重新整理權杖，該值與 **createdAt** 相同。 + - 若有重新整理權杖，該值反映最近一次存取權杖被刷新時的時間。 +- `hasRefreshToken`：是否有重新整理權杖可用。 + 若連接器支援離線存取且授權請求正確設定，Logto 會在身分提供者簽發時一併儲存重新整理權杖與存取權杖。 + 當存取權杖過期且有有效重新整理權杖時，Logto 會在使用者請求存取連接的提供者時自動嘗試以重新整理權杖取得新存取權杖。 +- `expiresAt`：存取權杖的預估過期時間（單位：**秒**）。 + 此值根據身分提供者權杖端點回傳的 `expires_in` 計算。（僅當提供者回傳 `expires_in` 時才有此欄位。） +- `scope`：存取權杖的權限範圍，表示身分提供者授予的權限。 + 有助於瞭解儲存的存取權杖可執行哪些操作。（僅當提供者回傳 `scope` 時才有此欄位。） +- `tokenType`：存取權杖的型別，通常為 "Bearer"。 + （僅當提供者回傳 `token_type` 時才有此欄位。） + +## 權杖擷取 \{#token-retrieval} + +啟用權杖儲存並將權杖安全儲存於 Logto Secret Vault 後，終端使用者可透過整合 Logto [Account API](/end-user-flows/account-settings/by-account-api) 從你的客戶端應用程式擷取其第三方存取權杖。 + +- `GET /my-account/identities/:target/access-token`：根據指定連接器 target（如 github、google）取得社交身分的存取權杖。 + +- `GET /my-account/sso-identities/:connectorId/access-token`：根據指定連接器 ID 取得企業級 SSO 身分的存取權杖。 + +:::info +瞭解如何[啟用](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api)與[存取](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) Account API（使用 Logto 簽發的存取權杖）。 +::: + +### 權杖輪替 \{#token-rotation} + +權杖擷取端點回傳： + +- `200` OK：成功取得且存取權杖仍有效。 +- `404` Not Found：使用者未有與指定 target 或連接器 ID 關聯的社交或企業級 SSO 身分，或未儲存存取權杖。 +- `401` Unauthorized：存取權杖已過期。 + +若存取權杖已過期且有重新整理權杖，Logto 會自動嘗試刷新存取權杖，並於回應中回傳新存取權杖。Secret Vault 中的權杖儲存也會同步更新新存取權杖及其中繼資料。 + +## 權杖儲存刪除 \{#token-storage-deletion} + +聯邦權杖儲存直接綁定於每位使用者的社交或企業級 SSO 連接。這表示在下列情況下，儲存的權杖集會自動刪除： + +- 關聯的社交或企業級 SSO 身分自使用者帳號移除。 +- 使用者帳號自你的租戶刪除。 +- 社交或企業級 SSO 連接器自你的租戶刪除。 + +### 撤銷權杖 \{#revoking-tokens} + +你也可以手動刪除使用者的第三方權杖集以撤銷存取： + +- 透過 Console： + 前往使用者身分詳細頁，滾動至 **Access token** 區塊（如有權杖儲存），點擊區塊底部的 **Delete tokens** 按鈕。 +- 透過 Management API： + - `DELETE /api/secret/:id`：根據 ID 刪除特定密鑰，可於使用者身分詳細頁取得該 ID。 + +撤銷權杖集後，使用者需重新與第三方提供者驗證以取得新存取權杖，方可再次存取第三方 API。 + +## 重新驗證與權杖更新 \{#reauthentication-and-token-renewal} + +當儲存的存取權杖已過期，或應用程式需請求額外 API 權限範圍時，終端使用者可重新與第三方提供者驗證以取得新的存取權杖——無需再次登入 Logto。 +這可透過 Logto [Social Verification API](https://openapi.logto.io/operation/operation-createverificationbysocial) 實現，讓使用者重新啟動聯邦社交授權流程並更新其權杖集。 + +:::note +重新啟動聯邦授權目前僅限於社交連接器。 +對於企業級 SSO 連接器，重新驗證與權杖更新需使用者重新啟動完整 Logto 驗證流程，因目前登入後不支援直接與企業級 SSO 提供者重新授權。 +::: + +```mermaid +sequenceDiagram + autonumber + + participant User as 使用者 (User) + participant Logto as Logto + participant Provider as 第三方提供者 (Third-party Provider) + + User->>Logto: post /api/verification/social + Logto->>User: 重新導向至第三方提供者 + User->>Provider: 驗證與授權 + Provider->>User: 以授權碼導回 + User->>Logto: post /api/verification/social/verify，帶授權碼 + Logto->>User: 回傳社交驗證 ID + User->>Logto: patch /my-account/identities/:target/access-token +``` + +1. 使用者呼叫 `POST /api/verification/social` 端點發起社交驗證請求。可指定自訂權限範圍（scope）以請求第三方提供者額外權限。 + + ```sh + curl -X POST https:///api/verification/social \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "state": "", + "connectorId": "", + "redirectUri": "", + "scope": "" + }' + ``` + + - **authorization header**：Logto 簽發的使用者存取權杖。 + - **connectorId**：Logto 中的社交連接器 ID。 + - **redirectUri**：驗證後導回你應用程式的 URI。需於提供者應用程式設定中註冊此 URI。 + - **scope**：（選填）自訂權限範圍，請求第三方提供者額外權限。未指定則使用連接器預設權限範圍。 + +2. Logto 建立新的社交驗證紀錄，並回傳社交驗證 ID 及授權 URL，讓使用者導向第三方提供者進行驗證。 + + 回應範例如下： + + ```json + { + "verificationRecordId": "", + "authorizationUri": "", + "expiresAt": "" + } + ``` + +3. 將使用者導向授權 URL。使用者於第三方提供者驗證並授權。 + +4. 第三方提供者以授權碼導回你的客戶端應用程式。 + +5. 處理授權回呼，將授權碼轉發至 Logto 驗證端點： + + ```sh + curl -X POST https:///api/verification/social/verify \ + -H "Authorization: Bearer " \ + -d '{ + "verificationRecordId": "", + "connectorData": { + "code": "", + "state": "", + "redirectUri": "" + } + }' + ``` + + - **authorization header**：Logto 簽發的使用者存取權杖。 + - **verificationRecordId**：前一步回傳的社交驗證 ID。 + - **connectorData**：授權碼及第三方提供者回呼時回傳的其他資料。 + + :::note + 請務必驗證 `state` 參數以防止 CSRF 攻擊。 + ::: + +6. Logto 驗證授權碼，並向第三方提供者換取新存取權杖與重新整理權杖，然後於回應中回傳社交驗證 ID。 + +7. 最後，呼叫 `PATCH /my-account/identities/:target/access-token` 端點並帶入社交驗證 ID，更新使用者的權杖儲存： + + ```sh + curl -X PATCH https:///my-account/identities//access-token \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "socialVerificationId": "" + }' + ``` + + - **authorization header**：Logto 簽發的使用者存取權杖。 + - **socialVerificationId**：前一步回傳的社交驗證紀錄 ID。 + + 這將以新存取權杖與重新整理權杖更新 Logto Secret Vault 中的使用者權杖集，讓使用者無需再次登入 Logto 即可存取第三方 API。 + + 更新後的存取權杖將會回傳。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx index 214e9319059..5fe3abcb557 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/personal-access-token.mdx @@ -10,36 +10,48 @@ sidebar_position: 4 ### 使用 Console \{#using-console} -你可以在 Console > 使用者管理 (User management) 的使用者詳情頁面管理個人存取權杖。在「驗證 (Authentication)」卡片中，你可以查看個人存取權杖清單並建立新的權杖。 +你可以在 Console > 使用者管理 的使用者詳細頁面管理個人存取權杖。在「驗證 (Authentication)」卡片中，你可以查看個人存取權杖清單並建立新的權杖。 ### 使用 Management API \{#using-management-api} -設定好 [Management API](/integrate-logto/interact-with-management-api/) 後，你可以使用 [API 端點](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) 來建立、列出及刪除個人存取權杖。 +設定好 [Management API](/integrate-logto/interact-with-management-api/) 後，你可以使用 [API 端點](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) 來建立、列出和刪除個人存取權杖。 -## 使用 PAT 取得存取權杖 \{#use-pats-to-grant-access-tokens} +## 使用 PAT 授予存取權杖 \{#use-pats-to-grant-access-tokens} -建立 PAT 後，你可以透過權杖交換端點，將其用於為你的應用程式取得存取權杖。 +建立 PAT 後，你可以透過權杖交換端點，使用它為你的應用程式授予存取權杖。 + +:::tip 權杖流程等價性 + +使用 PAT 取得的存取權杖，與標準 `refresh_token` 流程取得的權杖**完全相同**。這表示： + +- **組織情境**：PAT 取得的權杖支援與重新整理權杖 (Refresh token) 流程相同的組織權限與權限範圍 (Scopes) +- **授權流程**：你可以將 PAT 交換取得的存取權杖用於[組織權限 (Organization permissions)](/authorization/organization-permissions)與[組織層級 API 資源 (Organization-level API resources)](/authorization/organization-level-api-resources) +- **權杖驗證**：驗證邏輯完全一致——僅初始授權型態不同 + +如果你正在處理組織，無論使用 PAT 或重新整理權杖 (Refresh token)，存取模式與權限皆相同。 + +::: ### 請求 \{#request} -應用程式會以 HTTP POST 方法，向租戶的 [權杖端點 (token endpoint)](/integrate-logto/application-data-structure#token-endpoint) 發起[權杖交換請求 (token exchange request)](https://auth.wiki/authorization-code-flow#token-exchange-request)，並使用特殊的 grant type。HTTP 請求主體採用 `application/x-www-form-urlencoded` 格式，包含以下參數： +應用程式會以 HTTP POST 方法，向租戶的 [權杖端點 (Token endpoint)](/integrate-logto/application-data-structure#token-endpoint) 發送[權杖交換請求 (Token exchange request)](https://auth.wiki/authorization-code-flow#token-exchange-request)，並使用特殊的 grant type。HTTP 請求主體採用 `application/x-www-form-urlencoded` 格式，包含以下參數： 1. `client_id`：必填。應用程式的 client ID。 2. `grant_type`：必填。此參數值必須為 `urn:ietf:params:oauth:grant-type:token-exchange`，表示正在執行權杖交換。 -3. `resource`：選填。資源標示符 (resource indicator)，與其他權杖請求相同。 -4. `scope`：選填。請求的權限範圍 (scopes)，與其他權杖請求相同。 +3. `resource`：選填。資源標示符 (Resource indicator)，與其他權杖請求相同。 +4. `scope`：選填。請求的權限範圍 (Scopes)，與其他權杖請求相同。 5. `subject_token`：必填。使用者的 PAT。 -6. `subject_token_type`：必填。`subject_token` 參數所提供安全權杖的型別。此參數值必須為 `urn:logto:token-type:personal_access_token`。 +6. `subject_token_type`：必填。`subject_token` 參數所提供安全權杖的型態。此參數值必須為 `urn:logto:token-type:personal_access_token`。 ### 回應 \{#response} -若權杖交換請求成功，租戶的權杖端點會回傳一個代表使用者身分的存取權杖。回應內容以 `application/json` 格式，包含以下參數： +若權杖交換請求成功，租戶的權杖端點會回傳代表使用者身分的存取權杖。HTTP 回應主體採用 `application/json` 格式，包含以下參數： 1. `access_token`：必填。使用者的存取權杖，與 `authorization_code` 或 `refresh_token` 等其他權杖請求相同。 -2. `issued_token_type`：必填。發行權杖的型別。此參數值必須為 `urn:ietf:params:oauth:token-type:access_token`。 -3. `token_type`：必填。權杖型別。此參數值必須為 `Bearer`。 -4. `expires_in`：必填。存取權杖的有效秒數。 -5. `scope`：選填。存取權杖的權限範圍。 +2. `issued_token_type`：必填。發行權杖的型態。此參數值必須為 `urn:ietf:params:oauth:token-type:access_token`。 +3. `token_type`：必填。權杖型態。此參數值必須為 `Bearer`。 +4. `expires_in`：必填。存取權杖的存活時間（秒）。 +5. `scope`：選填。存取權杖的權限範圍 (Scopes)。 ### 權杖交換範例 \{#example-token-exchange} @@ -68,7 +80,7 @@ Content-Type: application/json } ``` -存取權杖範例 payload： +存取權杖 (Access token) 負載範例： ```json { @@ -85,9 +97,10 @@ Content-Type: application/json ## 相關資源 \{#related-resources} - 什麼是個人存取權杖？什麼時候該使用個人存取權杖？ + 什麼是個人存取權杖 (Personal access token)？什麼時候該使用個人存取權杖？ - 個人存取權杖、機器對機器驗證 (Machine-to-Machine authentication) 與 API 金鑰的定義及實際應用場景 + 個人存取權杖 (Personal Access Tokens)、機器對機器驗證 (Machine-to-Machine authentication) 與 API + 金鑰 (API Keys) 定義及實際應用場景 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx index 6bb71941183..2568c8638bf 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/user-migration.mdx @@ -4,23 +4,25 @@ sidebar_position: 5 # 使用者遷移 (User migration) -Logto 支援手動將現有使用者從其他平台遷移，本指南將說明如何透過 Management API 匯入現有使用者，並介紹遷移前你應考慮的事項。 +Logto 支援從其他平台手動遷移現有使用者。本指南將說明如何透過 Management API 匯入現有使用者，以及遷移前你應考慮的事項。 ## 使用者結構 (User schema) \{#user-schema} 在開始之前，讓我們先看看 Logto 的 [使用者結構](/user-management/user-data/#user-profile)。你需要注意使用者結構的三個部分： 1. **基本資料 (Basic data)**：來自使用者檔案的基本資訊，你可以將現有使用者檔案的資料對應到這裡。 -2. **自訂資料 (Custom data)**：儲存額外的使用者資訊，適合存放無法對應到基本資料的欄位。 +2. **自訂資料 (Custom data)**：儲存額外的使用者資訊，可用於存放無法對應到基本資料的欄位。 3. **社交身分 (Social identities)**：儲存從社交登入取得的使用者資訊。 -你可以建立一個對應表，將現有使用者檔案的資訊對應到 **基本資料 (basic data)** 與 **自訂資料 (custom data)**。若有社交登入，需額外步驟匯入社交身分，請參考 [連結社交身分至使用者 (Link social identity to user)](https://openapi.logto.io/operation/operation-createuseridentity) 的 API。 +你可以建立對照表，將現有使用者檔案的資訊對應到 **基本資料 (basic data)** 與 **自訂資料 (custom data)**。若有社交登入，需額外步驟匯入社交身分，請參考 [連結社交身分至使用者 (Link social identity to user)](https://openapi.logto.io/operation/operation-createuseridentity) 的 API。 ## 密碼雜湊 (Password hashing) \{#password-hashing} -Logto 使用 [Argon2](https://en.wikipedia.org/wiki/Argon2) 進行使用者密碼雜湊，並為遷移方便，也支援 `MD5`、`SHA1`、`SHA256` 和 `Bcrypt` 等其他演算法。這些演算法被認為不安全，對應的密碼雜湊值會在使用者首次成功登入時自動遷移為 Argon2。 +Logto 使用 [Argon2](https://en.wikipedia.org/wiki/Argon2) 進行使用者密碼雜湊，並為遷移方便支援其他演算法，如 `MD5`、`SHA1`、`SHA256` 及 `Bcrypt`。這些演算法被認為不安全，對應的密碼雜湊值會在使用者首次成功登入時自動遷移為 Argon2。 -如果你使用其他雜湊演算法或加鹽，可以將 `passwordAlgorithm` 設為 `Legacy`，這樣可使用 Node.js 支援的任何雜湊演算法。支援的演算法列表可參考 [Node.js crypto 文件](https://nodejs.org/api/crypto.html#cryptogethashes)。此情況下，`passwordDigest` 需為包含雜湊演算法及其他參數的 JSON 字串。 +如果你使用其他雜湊演算法或加鹽，可以將 `passwordAlgorithm` 設為 `Legacy`，這允許你使用 Node.js 支援的任何雜湊演算法。支援的演算法列表可參考 [Node.js crypto 文件](https://nodejs.org/api/crypto.html#cryptogethashes)。此情況下，`passwordDigest` 需為包含雜湊演算法及其他參數的 JSON 字串。 + +### 一般 Legacy 格式 \{#general-legacy-format} JSON 字串格式如下： @@ -28,9 +30,9 @@ JSON 字串格式如下： ["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"] ``` -你可以用 `@` 作為參數中的實際密碼值佔位符。 +你可以用 `@` 作為實際密碼值的佔位符。 -例如，若你使用 SHA256 並加鹽，可將密碼儲存為下列格式： +例如，若你使用 SHA256 並加鹽，可如下儲存密碼： ```json ["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"] @@ -44,10 +46,40 @@ hash.update('salt123' + 'password123'); const expectedHashedValue = hash.digest('hex'); ``` +### PBKDF2 支援 \{#pbkdf2-support} + +Logto 特別支援 [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2)。 + +若要遷移 PBKDF2 雜湊的密碼，請將 `passwordAlgorithm` 設為 `Legacy`，並將 `passwordDigest` 格式化如下： + +```json +["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"] +``` + +參數說明： + +- **`salt`**：原始雜湊時使用的鹽值 +- **`iterations`**：迭代次數（如 `"1000"`） +- **`keylen`**：導出金鑰長度（位元組，例 `"20"`） +- **`digest`**：使用的雜湊函式（如 `"sha512"`、`"sha256"`、`"sha1"`） +- **`@`**：實際密碼值的佔位符 +- **`expected_hashed_value`**：預期的雜湊結果（十六進位字串） + +**範例遷移 payload：** + +```json +{ + "username": "john_doe", + "primaryEmail": "john.doe@example.com", + "passwordAlgorithm": "Legacy", + "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]" +} +``` + ## 遷移步驟 (Steps to migrate) \{#steps-to-migrate} -1. **準備使用者資料 (Prepare the user data)** - 你應先從現有平台匯出使用者資料，並將使用者資訊對應到 Logto 的使用者結構。我們建議你將對應後的資料整理為 JSON 格式。以下為使用者資料範例： +1. **準備使用者資料** + 你應先從現有平台匯出使用者資料，並將資訊對應到 Logto 的使用者結構。我們建議你將對應後的資料整理為 JSON 格式。以下為範例： ```json [ @@ -64,12 +96,12 @@ const expectedHashedValue = hash.digest('hex'); ] ``` -2. **建立 Logto 租戶 (Create a Logto tenant)** +2. **建立 Logto 租戶 (tenant)** 你需要在 Logto 建立一個租戶。可選擇 Logto Cloud 或 Logto OSS。若尚未建立，請參考 [設定 Logto Cloud](/introduction/set-up-logto-cloud/#create-logto-tenant) 指南。 -3. **設定 Management API 連線 (Setup the connection of Management API)** - 我們將使用 Management API 匯入使用者資料，請參考 [Management API](/integrate-logto/interact-with-management-api) 了解如何在開發環境中設定連線。 -4. **匯入使用者資料 (Import the user data)** - 建議你撰寫腳本逐一匯入使用者資料，將呼叫 [建立使用者 (create user)](https://openapi.logto.io/operation/operation-createuser) API 來匯入。以下為腳本範例： +3. **設置 Management API 連線** + 我們將使用 Management API 匯入使用者資料，請參考 [Management API](/integrate-logto/interact-with-management-api) 了解如何在開發環境設置連線。 +4. **匯入使用者資料** + 建議你撰寫腳本逐一匯入使用者資料，將呼叫 [建立使用者 (create user)](https://openapi.logto.io/operation/operation-createuser) API。以下為腳本範例： ```jsx const users = require('./users.json'); @@ -85,7 +117,7 @@ const expectedHashedValue = hash.digest('hex'); }, body: JSON.stringify(user), }); - // Sleep for a while to avoid rate limit + // 為避免觸發速率限制，請暫停一段時間 await new Promise((resolve) => setTimeout(resolve, 200)); } catch (error) { console.error(`Failed to import user ${user.username}: ${error.message}`); @@ -96,7 +128,7 @@ const expectedHashedValue = hash.digest('hex'); importUsers(); ``` -請注意 API 端點有速率限制，你應在每次請求間加入延遲以避免觸發限制。詳情請參閱 [速率限制 (rate limits)](/integrate-logto/interact-with-management-api/#rate-limit) 頁面。 +請注意，API 端點有速率限制，請於每次請求間加入暫停以避免觸發限制。詳情請參閱 [速率限制](/integrate-logto/interact-with-management-api/#rate-limit) 頁面。 若你有大量使用者資料（10 萬以上），可[聯絡我們](https://logto.io/contact)以提升速率限制。