diff --git a/docs/connectors/social.mdx b/docs/connectors/social.mdx index a026247ac91..8fa48559167 100644 --- a/docs/connectors/social.mdx +++ b/docs/connectors/social.mdx @@ -139,7 +139,7 @@ Please note the following settings: Once you create a social connector successfully, you can enable it as a Social login button (e.g., Continue with Google) in Sign-in Experience. -1. Navigate to Console > Sign-in experience >Sign-up and sign-in. +1. Navigate to Console > Sign-in experience > Sign-up and sign-in. 2. (Optional) Choose "Not applicable" for sign-up identifier if you need social login only. 3. Add configured social connectors to the "Social sign-in" section. 4. Reorder connectors as needed. diff --git a/docs/integrations/email/aws-ses/README.mdx b/docs/integrations/email/aws-ses/README.mdx index f42a48e865f..ff80365c3a9 100644 --- a/docs/integrations/email/aws-ses/README.mdx +++ b/docs/integrations/email/aws-ses/README.mdx @@ -5,10 +5,15 @@ sidebar_custom_props: description: Amazon SES is a cloud email service provider that can integrate into any application for bulk email sending. logoFilename: 'aws.svg' darkLogoFilename: 'aws-dark.svg' +tutorial_name: AWS SES +tutorial_config_name: AWS SES email connector +tutorial_sign_up_identifier: Email address --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up email verification with AWS Direct Mail The official Logto connector for AWS connector for direct mail service. @@ -21,55 +26,4 @@ Amazon SES is a cloud email service provider that can integrate into any applica Logto team to call the Amazon Simple Email Service APIs, with the help of which Logto end-users can register and sign in to their Logto account via mail verification code. -## Configure a mail service in the AWS service console \{#configure-a-mail-service-in-the-aws-service-console} - -### Register AWS account \{#register-aws-account} - -Go to [AWS](https://aws.amazon.com/) and register an account. - -### Create a identity \{#create-a-identity} - -- Go to `Amazon Simple Email Service` Console -- Create an identity, choose one of the following options - - Create an domain - - Create an email address - -### Configuration of the connector \{#configuration-of-the-connector} - -1. Click your username in the upper right corner of the Amazon console to enter `Security Credentials`. If you don't have one, create an `AccessKey` and save it carefully. -2. Complete the settings of the `Amazon Simple Email Service` connector: - - Use the `AccessKey ID` and `AccessKey Secret` obtained in step 1 to fill in `accessKeyId` and `accessKeySecret` respectively. - - `region`: Fill in the `region` field with the region of the identity you use to send mail. - - `emailAddress`: The email address you use to send mail, in the format of `Logto\` or `\` - -the following parameters are optional; parameters description can be found in the [AWS SES API documentation](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html). - -- `feedbackForwardingEmailAddress` -- `feedbackForwardingEmailAddressIdentityArn` -- `configurationSetName` - -### Test the Amazon SES connector \{#test-the-amazon-ses-connector} - -You can type in an email address and click on "Send" to see whether the settings work before "Save and Done". - -That's it. Don't forget to [Enable connector in sign-in experience](/connectors/email-connectors/#enable-email-sign-up-or-sign-in). - -### Configure types \{#configure-types} - -| Name | Type | -| ----------------------------------------- | ----------------- | -| accessKeyId | string | -| accessKeySecret | string | -| region | string | -| emailAddress | string (OPTIONAL) | -| emailAddressIdentityArn | string (OPTIONAL) | -| feedbackForwardingEmailAddress | string (OPTIONAL) | -| feedbackForwardingEmailAddressIdentityArn | string (OPTIONAL) | -| configurationSetName | string (OPTIONAL) | -| templates | Template[] | - -| Template Properties | Type | Enum values | -| ------------------- | ----------- | ------------------------------------------------------- | -| subject | string | N/A | -| content | string | N/A | -| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' | + diff --git a/tutorial/build-with-logto/_connector-aws-ses.mdx b/docs/integrations/email/aws-ses/_integration.mdx similarity index 76% rename from tutorial/build-with-logto/_connector-aws-ses.mdx rename to docs/integrations/email/aws-ses/_integration.mdx index ee84c868f24..35f28c4a59d 100644 --- a/tutorial/build-with-logto/_connector-aws-ses.mdx +++ b/docs/integrations/email/aws-ses/_integration.mdx @@ -1,31 +1,23 @@ -### Configure a mail service in the AWS service console +## Configure a mail service in the AWS service console \{#configure-a-mail-service-in-the-aws-service-console} -Amazon SES is a cloud email service provider that can integrate into any application for bulk email sending. - -Logto core calls the Amazon Simple Email Service APIs via this connector, with the help of which Logto end-users can register and sign in to their Logto account via email verification code. - -> 💡 **Tip** -> -> You can skip some sections if you have already finished. - -#### Register AWS account +### Register AWS account \{#register-aws-account} Go to [AWS](https://aws.amazon.com/) and register an account. -#### Create a identity +### Create a identity \{#create-a-identity} - Go to `Amazon Simple Email Service` Console - Create an identity, choose one of the following options - - Create a domain + - Create an domain - Create an email address -#### Configuration of the connector +### Configuration of the connector \{#configuration-of-the-connector} 1. Click your username in the upper right corner of the Amazon console to enter `Security Credentials`. If you don't have one, create an `AccessKey` and save it carefully. 2. Complete the settings of the `Amazon Simple Email Service` connector: - Use the `AccessKey ID` and `AccessKey Secret` obtained in step 1 to fill in `accessKeyId` and `accessKeySecret` respectively. - `region`: Fill in the `region` field with the region of the identity you use to send mail. - - `emailAddress`: The email address you use to send mail, in the format of `Logto` or `` + - `emailAddress`: The email address you use to send mail, in the format of `Logto\` or `\` the following parameters are optional; parameters description can be found in the [AWS SES API documentation](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html). @@ -33,13 +25,13 @@ the following parameters are optional; parameters description can be found in th - `feedbackForwardingEmailAddressIdentityArn` - `configurationSetName` -#### Test the Amazon SES connector +### Test the Amazon SES connector \{#test-the-amazon-ses-connector} You can type in an email address and click on "Send" to see whether the settings work before "Save and Done". -That's it. Don't forget to enable connector in sign-in experience. +That's it. Don't forget to [Enable connector in sign-in experience](/connectors/email-connectors/#enable-email-sign-up-or-sign-in). -#### Configure types +### Configure types \{#configure-types} | Name | Type | | ----------------------------------------- | ----------------- | diff --git a/docs/integrations/email/sendgrid/README.mdx b/docs/integrations/email/sendgrid/README.mdx new file mode 100644 index 00000000000..5fa13987e84 --- /dev/null +++ b/docs/integrations/email/sendgrid/README.mdx @@ -0,0 +1,26 @@ +--- +slug: /integrations/sendgrid-email +sidebar_label: SendGrid Email +sidebar_custom_props: + description: SendGrid is a communication platform for transactional and marketing email. + logoFilename: 'sendgrid.svg' +tutorial_name: SendGrid +tutorial_config_name: SendGrid email connector +tutorial_sign_up_identifier: Email address +--- + +import GuideTip from '../../fragments/_guide-tip.mdx'; + +import Integration from './_integration.mdx'; + +# Set up email verification with SendGrid Email + +The official Logto connector for SendGrid email service. + + + +## Get started \{#get-started} + +SendGrid (i.e. Twilio SendGrid) is a customer communication platform for transactional and marketing email. We can use its email sending function to send a _verification code_. + + diff --git a/docs/integrations/email/sendgrid-email/README.mdx b/docs/integrations/email/sendgrid/_integration.mdx similarity index 89% rename from docs/integrations/email/sendgrid-email/README.mdx rename to docs/integrations/email/sendgrid/_integration.mdx index cd561bd5b35..6cc655d2a43 100644 --- a/docs/integrations/email/sendgrid-email/README.mdx +++ b/docs/integrations/email/sendgrid/_integration.mdx @@ -1,23 +1,3 @@ ---- -slug: /integrations/sendgrid-email -sidebar_label: SendGrid Email -sidebar_custom_props: - description: SendGrid is a communication platform for transactional and marketing email. - logoFilename: 'sendgrid.svg' ---- - -import GuideTip from '../../fragments/_guide-tip.mdx'; - -# Set up email verification with SendGrid Email - -The official Logto connector for SendGrid email service. - - - -## Get started \{#get-started} - -SendGrid (i.e. Twilio SendGrid) is a customer communication platform for transactional and marketing email. We can use its email sending function to send a _verification code_. - ## Register SendGrid account \{#register-sendgrid-account} Create a new account at [SendGrid website](https://app.sendgrid.com/). You may skip this step if you've already got an account. diff --git a/docs/integrations/sms/twilio/README.mdx b/docs/integrations/sms/twilio/README.mdx new file mode 100644 index 00000000000..df987e11a3d --- /dev/null +++ b/docs/integrations/sms/twilio/README.mdx @@ -0,0 +1,30 @@ +--- +slug: /integrations/twilio-sms +sidebar_label: Twilio SMS +sidebar_custom_props: + description: Twilio provides programmable communication tools for phone calls and messages. + logoFilename: 'twilio.svg' +tutorial_name: Twilio +tutorial_config_name: Twilio SMS connector +tutorial_sign_up_identifier: Phone number +--- + +import GuideTip from '../../fragments/_guide-tip.mdx'; + +import Integration from './_integration.mdx'; + +# Set up SMS verification with Twilio SMS + +The official Logto connector for Twilio short message service. + + + +## Get started \{#get-started} + +Twilio provides programmable communication tools for making and receiving phone calls, sending and receiving text messages, and other communication functions. We can send the "verification code" text messages through its web service APIs. + + + +## Reference \{#reference} + +Twilio - Error and Warning Dictionary diff --git a/docs/integrations/sms/twilio-sms/README.mdx b/docs/integrations/sms/twilio/_integration.mdx similarity index 80% rename from docs/integrations/sms/twilio-sms/README.mdx rename to docs/integrations/sms/twilio/_integration.mdx index 5899b288731..846f08fd64a 100644 --- a/docs/integrations/sms/twilio-sms/README.mdx +++ b/docs/integrations/sms/twilio/_integration.mdx @@ -1,23 +1,3 @@ ---- -slug: /integrations/twilio-sms -sidebar_label: Twilio SMS -sidebar_custom_props: - description: Twilio provides programmable communication tools for phone calls and messages. - logoFilename: 'twilio.svg' ---- - -import GuideTip from '../../fragments/_guide-tip.mdx'; - -# Set up SMS verification with Twilio SMS - -The official Logto connector for Twilio short message service. - - - -## Get started \{#get-started} - -Twilio provides programmable communication tools for making and receiving phone calls, sending and receiving text messages, and other communication functions. We can send the "verification code" text messages through its web service APIs. - ## Register Twilio account \{#register-twilio-account} Create a new account on [Twilio](https://www.twilio.com). (Jump to the next step if you already have one.) @@ -77,7 +57,3 @@ That's it. Don't forget to [Enable connector in sign-in experience](/connectors/ | ------------------- | ----------- | ------------------------------------------------------- | | content | string | N/A | | usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' | - -## Reference \{#reference} - -Twilio - Error and Warning Dictionary diff --git a/docs/integrations/social/apple/README.mdx b/docs/integrations/social/apple/README.mdx index d558e6d0350..d8fafced9f1 100644 --- a/docs/integrations/social/apple/README.mdx +++ b/docs/integrations/social/apple/README.mdx @@ -4,10 +4,13 @@ sidebar_label: Apple sidebar_custom_props: darkLogoFilename: 'apple-dark.svg' description: Apple is a multinational high-end provider of hardware and software. +tutorial_config_name: Apple Sign-in --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with Apple The official Logto connector for Apple social sign-in. @@ -18,67 +21,7 @@ The official Logto connector for Apple social sign-in. If you don't know the concept of the connector or don't know how to add this connector to your Sign-in experience, please see [Logto tutorial](/connectors/social-connectors). -:::note - -Apple sign-in is required for AppStore if you have other social sign-in methods in your app. -Having Apple sign-in on Android devices is great if you also provide an Android app. - -::: - -You need to enroll [Apple Developer Program](https://developer.apple.com/programs/) before continuing. - -### Enable Sign in with Apple for your app \{#enable-sign-in-with-apple-for-your-app} - -:::caution - -Even if you want to implement Sign in with Apple on a web app only, you still need to have an existing app that embraces the AppStore ecosystem (i.e., have a valid App ID). - -::: - -You can do it via Xcode -> Project settings -> Signing & Capabilities, or visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/bundleId). - -![Enable Sign in with Apple](./assets/enable-sign-in-with-apple-in-xcode.png) - -See the "Enable an App ID" section in [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/configuring_your_environment_for_sign_in_with_apple) for more info. - -### Create an identifier \{#create-an-identifier} - -1. Visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/serviceId), then click the "+" button next to "Identifier". -2. In the "Register a new identifier" page, choose "Services IDs" and click "Continue". -3. Fill out "Description" and "Identifier" (E.g., `Logto Test` and `io.logto.test`), then click "Continue". -4. Double-check the info and click "Register". - -### Enable Sign in with Apple for your identifier \{#enable-sign-in-with-apple-for-your-identifier} - -Click the identifier you just created. Check "Sign in with Apple" on the details page and click "Configure". - -![Enable Sign in with Apple](./assets/enable-sign-in-with-apple.png) - -In the opening modal, select the App ID you just enabled Sign in with Apple. - -Enter the domain of your Logto instance without protocol and port, e.g., `your.logto.domain`; then enter the "Return URL" (i.e., Redirect URI), which is the Logto URL with `/callback/${connector_id}`, e.g., `https://your.logto.domain/callback/apple-universal`. You can get the randomly generated `connector_id` after creating Apple connector in Admin Console. - -![domain-and-url](./assets/domain-and-url.png) - -Click "Next" then "Done" to close the modal. Click "Continue" on the top-right corner, then click "Save" to save your configuration. - -:::caution - -Apple does NOT allow Return URLs with HTTP protocol and `localhost` domain. - -If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS. - -::: - -## Configure scope \{#configure-scope} - -To get user's email from Apple, you need to configure the scope to include `email`. For both email and name, you can use `name email` as the scope. See [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113) for more info. - -:::note - -The user may choose to hide their email address from your app. In this case, you will not be able to retrieve the real email address. An email address like `random@privaterelay.appleid.com` will be returned instead. - -::: + ### Pitfalls of configuring scope \{#pitfalls-of-configuring-scope} diff --git a/tutorial/build-with-logto/_connector-apple.mdx b/docs/integrations/social/apple/_integration.mdx similarity index 53% rename from tutorial/build-with-logto/_connector-apple.mdx rename to docs/integrations/social/apple/_integration.mdx index 5a08cc09fd3..b9dce8c6b41 100644 --- a/tutorial/build-with-logto/_connector-apple.mdx +++ b/docs/integrations/social/apple/_integration.mdx @@ -1,15 +1,19 @@ -> ℹ️ **Note** -> -> Apple sign-in is required for AppStore if you have other social sign-in methods in your app. -> Having Apple sign-in on Android devices is great if you also provide an Android app. +:::note + +Apple sign-in is required for AppStore if you have other social sign-in methods in your app. +Having Apple sign-in on Android devices is great if you also provide an Android app. + +::: You need to enroll [Apple Developer Program](https://developer.apple.com/programs/) before continuing. -### Enable Sign in with Apple for your app +### Enable Sign in with Apple for your app \{#enable-sign-in-with-apple-for-your-app} + +:::caution + +Even if you want to implement Sign in with Apple on a web app only, you still need to have an existing app that embraces the AppStore ecosystem (i.e., have a valid App ID). -> ⚠️ **Caution** -> -> Even if you want to implement Sign in with Apple on a web app only, you still need to have an existing app that embraces the AppStore ecosystem (i.e., have a valid App ID). +::: You can do it via Xcode -> Project settings -> Signing & Capabilities, or visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/bundleId). @@ -17,14 +21,14 @@ You can do it via Xcode -> Project settings -> Signing & Capabilities, or visit See the "Enable an App ID" section in [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/configuring_your_environment_for_sign_in_with_apple) for more info. -### Create an identifier +### Create an identifier \{#create-an-identifier} 1. Visit [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/serviceId), then click the "+" button next to "Identifier". 2. In the "Register a new identifier" page, choose "Services IDs" and click "Continue". 3. Fill out "Description" and "Identifier" (E.g., `Logto Test` and `io.logto.test`), then click "Continue". 4. Double-check the info and click "Register". -### Enable Sign in with Apple for your identifier +### Enable Sign in with Apple for your identifier \{#enable-sign-in-with-apple-for-your-identifier} Click the identifier you just created. Check "Sign in with Apple" on the details page and click "Configure". @@ -38,24 +42,20 @@ Enter the domain of your Logto instance without protocol and port, e.g., `your.l Click "Next" then "Done" to close the modal. Click "Continue" on the top-right corner, then click "Save" to save your configuration. -> ⚠️ **Caution** -> -> Apple does NOT allow Return URLs with HTTP protocol and `localhost` domain. -> -> If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS. +:::caution + +Apple does NOT allow Return URLs with HTTP protocol and `localhost` domain. + +If you want to test locally, you need to edit `/etc/hosts` file to map localhost to a custom domain and set up a local HTTPS environment. [mkcert](https://github.com/FiloSottile/mkcert) can help you for setting up local HTTPS. + +::: + +## Configure scope \{#configure-scope} -### Compose the connector JSON +To get user's email from Apple, you need to configure the scope to include `email`. For both email and name, you can use `name email` as the scope. See [Apple official docs](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms#3332113) for more info. -You need to use the identifier that fills in the [Create an identifier](#create-an-identifier) section to compose the JSON: +:::note -```json -{ - "clientId": "io.logto.test" -} -``` +The user may choose to hide their email address from your app. In this case, you will not be able to retrieve the real email address. An email address like `random@privaterelay.appleid.com` will be returned instead. -> ℹ️ **Note** -> -> This connector doesn't support customizing `scope` (e.g., name, email) yet since Apple requires `form_post` response mode when `scope` is not empty, which is incompatible with the current connector design. -> -> We'll figure out this later. +::: diff --git a/docs/integrations/social/azure-ad/README.mdx b/docs/integrations/social/azure-ad/README.mdx new file mode 100644 index 00000000000..524c29dd42d --- /dev/null +++ b/docs/integrations/social/azure-ad/README.mdx @@ -0,0 +1,26 @@ +--- +slug: /integrations/azuread +sidebar_label: Microsoft +sidebar_custom_props: + description: Microsoft Azure Active Directory is a leading AD provider. +tutorial_name: Azure AD +tutorial_config_name: Azure AD +--- + +import GuideTip from '../../fragments/_guide-tip.mdx'; + +import Integration from './_integration.mdx'; + +# Set up login with Microsoft Azure AD + +The Microsoft Azure AD connector provides a succinct way for your application to use Azure’s OAuth 2.0 authentication system. + + + + + +## References \{#references} + + + Web app that signs in users + diff --git a/docs/integrations/social/azuread/README.mdx b/docs/integrations/social/azure-ad/_integration.mdx similarity index 82% rename from docs/integrations/social/azuread/README.mdx rename to docs/integrations/social/azure-ad/_integration.mdx index c58558399bb..58e19065da7 100644 --- a/docs/integrations/social/azuread/README.mdx +++ b/docs/integrations/social/azure-ad/_integration.mdx @@ -1,18 +1,3 @@ ---- -slug: /integrations/azuread -sidebar_label: Microsoft -sidebar_custom_props: - description: Microsoft Azure Active Directory is a leading AD provider. ---- - -import GuideTip from '../../fragments/_guide-tip.mdx'; - -# Set up login with Microsoft Azure AD - -The Microsoft Azure AD connector provides a succinct way for your application to use Azure’s OAuth 2.0 authentication system. - - - ## Set up Microsoft Azure AD in the Azure Portal \{#set-up-microsoft-azure-ad-in-the-azure-portal} - Visit the [Azure Portal](https://portal.azure.com/#home) and sign in with your Azure account. You need to have an active subscription to access Microsoft Azure AD. @@ -51,9 +36,3 @@ Logto will use this field to construct the authorization endpoints. This value i - If you select **Accounts in any organizational directory** for access type then you need to enter **organizations**. - If you select **Accounts in any organizational directory or personal Microsoft accounts** for access type then you need to enter **common**. - If you select **Personal Microsoft accounts only** for access type then you need to enter **consumers**. - -## References \{#references} - - - Web app that signs in users - diff --git a/docs/integrations/social/discord/README.mdx b/docs/integrations/social/discord/README.mdx index 11360c77c5f..5ba9946d7ff 100644 --- a/docs/integrations/social/discord/README.mdx +++ b/docs/integrations/social/discord/README.mdx @@ -3,45 +3,17 @@ slug: /integrations/discord sidebar_label: Discord sidebar_custom_props: description: Discord is the easiest way to talk over voice, video, and text. +tutorial_config_name: Discord OAuth app --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with Discord (OAuth 2.0) The Discord connector provides a way for your application to use Discord as an authorization system. -## Register a developer application \{#register-a-developer-application} - -- Visit [Discord Developer Portal](https://discord.com/developers/applications) and sign in with your Discord account. -- Click the **New Application** button to create an application, choose a name for it (Ex: LogtoAuth), tick the box and click **Create**. -- Go to **OAuth2** page and click **Reset Secret** -- Take note of the **CLIENT ID** and **CLIENT SECRET** fields -- Add the valid redirects (Ex: **`http://auth.mycompany.io/callback/${connector_id}`**). The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. - -## Configure Logto \{#configure-logto} - -### Config types \{#config-types} - -| Name | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | - -#### clientId \{#clientid} - -`clientId` is the `CLIENT ID` field we saved earlier. -(You can find it in the Oauth2 Page in Discord Developer Portal.) - -#### clientSecret \{#clientsecret} - -`clientSecret` is the `CLIENT SECRET` we saved earlier. -(If you've lost it you need to click **Reset Secret**) - -#### scope \{#scope} - -`scope` is the permissions granted by the user's authorization. The default value is `identify email`. -You can see the full list of scopes [here](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes). + diff --git a/tutorial/build-with-logto/_connector-discord.mdx b/docs/integrations/social/discord/_integration.mdx similarity index 60% rename from tutorial/build-with-logto/_connector-discord.mdx rename to docs/integrations/social/discord/_integration.mdx index 28ceb477ca9..02138f64224 100644 --- a/tutorial/build-with-logto/_connector-discord.mdx +++ b/docs/integrations/social/discord/_integration.mdx @@ -1,4 +1,4 @@ -### Register a developer application +### Register a developer application \{#register-a-developer-application} - Visit [Discord Developer Portal](https://discord.com/developers/applications) and sign in with your Discord account. - Click the **New Application** button to create an application, choose a name for it (Ex: LogtoAuth), tick the box and click **Create**. @@ -6,21 +6,27 @@ - Take note of the **CLIENT ID** and **CLIENT SECRET** fields - Add the valid redirects (Ex: **`http://auth.mycompany.io/callback/${connector_id}`**). The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. -### Configure Logto +## Configure Logto \{#configure-logto} -#### Config types +### Config types \{#config-types} | Name | Type | | ------------ | ------ | | clientId | string | | clientSecret | string | +| scope | string | -#### clientId +#### clientId \{#clientid} `clientId` is the `CLIENT ID` field we saved earlier. (You can find it in the Oauth2 Page in Discord Developer Portal.) -#### clientSecret +#### clientSecret \{#clientsecret} `clientSecret` is the `CLIENT SECRET` we saved earlier. -(If you've lost it you need to click **Reset Secret**) +(If you've lost it you need to click **Reset Secret**.) + +#### scope \{#scope} + +`scope` is the permissions granted by the user's authorization. The default value is `identify email`. +You can see the full list of scopes [here](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes). diff --git a/docs/integrations/social/facebook/README.mdx b/docs/integrations/social/facebook/README.mdx index 4b475377158..83bcf6545a0 100644 --- a/docs/integrations/social/facebook/README.mdx +++ b/docs/integrations/social/facebook/README.mdx @@ -3,10 +3,13 @@ slug: /integrations/facebook sidebar_label: Facebook sidebar_custom_props: description: Facebook is a worldwide social media platform with billions of users. +tutorial_config_name: Facebook login --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with Facebook The official Logto connector for Facebook social sign-in. @@ -17,61 +20,7 @@ The official Logto connector for Facebook social sign-in. The Facebook connector provides a concise way for your application to use Facebook's OAuth 2.0 authentication system. -### Register a Facebook developer account \{#register-a-facebook-developer-account} - -[Register as a Facebook Developer](https://developers.facebook.com/docs/development/register/) if you don't already have one - -### Set up a Facebook app \{#set-up-a-facebook-app} - -1. Visit the [Apps](https://developers.facebook.com/apps) page. -2. Click your existing app or [create a new one](https://developers.facebook.com/docs/development/create-an-app) if needed. - - The selected [app type](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types) is up to you, but it should have the product _Facebook Login_. -3. On the app dashboard page, scroll to the "Add a product" section and click the "Set up" button on the "Facebook Login" card. -4. Skip the Facebook Login Quickstart page, and click the sidebar -> "Products" -> "Facebook Login" -> "Settings". -5. In the Facebook Login Settings page, fill `${your_logto_origin}/callback/${connector_id}` in the "Valid OAuth Redirect URIs" field. The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. E.g.: - - `https://logto.dev/callback/${connector_id}` for production - - `https://localhost:3001/callback/${connector_id}` for testing in the local environment -6. Click the "Save changes" button at the bottom right corner. - -## Compose the connector JSON \{#compose-the-connector-json} - -1. In the Facebook app dashboard page, click the sidebar -> "Settings" -> "Basic". -2. You will see the "App ID" and "App secret" on the panel. -3. Click the "Show" button following the App secret input box to copy its content. -4. Fill out the Logto connector settings: - - Fill out the `clientId` field with the string from _App ID_. - - Fill out the `clientSecret` field with the string from _App secret_. - - Fill out the `scope` field with a comma or space separated list of [permissions](https://developers.facebook.com/docs/permissions/reference) in string. If you do not specify a scope, the default scope is `email,public_profile`. - -## Test sign-in with Facebook's test users \{#test-sign-in-with-facebooks-test-users} - -You can use the accounts of the test, developer, and admin users to test sign-in with the related app under both development and live [app modes](https://developers.facebook.com/docs/development/build-and-test/app-modes). - -You can also [take the app live](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode) directly so that any Facebook user can sign in with the app. - -- In the app dashboard page, click the sidebar -> "Roles" -> "Test Users". -- Click the "Create test users" button to create a testing user. -- Click the "Options" button of the existing test user, and you will see more operations, e.g., "Change name and password". - -## Publish Facebook sign-in settings \{#publish-facebook-sign-in-settings} - -Usually, only the test, admin, and developer users can sign in with the related app under [development mode](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode). - -To enable normal Facebook users sign-in with the app in the production environment, you maybe need to switch your Facebook app to _[live mode](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_, depending on the app type. -E.g., the pure _business type_ app doesn't have the "live" switch button, but it won't block your use. - -1. In the Facebook app dashboard page, click the sidebar -> "Settings" -> "Basic". -2. Fill out the "Privacy Policy URL" and "User data deletion" fields on the panel if required. -3. Click the "Save changes" button at the bottom right corner. -4. Click the "Live" switch button on the app top bar. - -## Config types \{#config-types} - -| Name | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | + ## References \{#references} diff --git a/tutorial/build-with-logto/_connector-facebook.mdx b/docs/integrations/social/facebook/_integration.mdx similarity index 59% rename from tutorial/build-with-logto/_connector-facebook.mdx rename to docs/integrations/social/facebook/_integration.mdx index 0c8da4a2125..35578162586 100644 --- a/tutorial/build-with-logto/_connector-facebook.mdx +++ b/docs/integrations/social/facebook/_integration.mdx @@ -1,8 +1,8 @@ -### Register a Facebook developer account +### Register a Facebook developer account \{#register-a-facebook-developer-account} -[Register as a Facebook Developer](https://developers.facebook.com/docs/development/register/) if you don't have one. +[Register as a Facebook Developer](https://developers.facebook.com/docs/development/register/) if you don't already have one -### Set up a Facebook app +### Set up a Facebook app \{#set-up-a-facebook-app} 1. Visit the [Apps](https://developers.facebook.com/apps) page. 2. Click your existing app or [create a new one](https://developers.facebook.com/docs/development/create-an-app) if needed. @@ -10,44 +10,46 @@ 3. On the app dashboard page, scroll to the "Add a product" section and click the "Set up" button on the "Facebook Login" card. 4. Skip the Facebook Login Quickstart page, and click the sidebar -> "Products" -> "Facebook Login" -> "Settings". 5. In the Facebook Login Settings page, fill `${your_logto_origin}/callback/${connector_id}` in the "Valid OAuth Redirect URIs" field. The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. E.g.: - - `https://your-logto-domain.com/callback/${connector_id}` for production + - `https://logto.dev/callback/${connector_id}` for production - `https://localhost:3001/callback/${connector_id}` for testing in the local environment 6. Click the "Save changes" button at the bottom right corner. -7. In the Facebook app dashboard page, click the sidebar -> "Settings" -> "Basic" and then you will get the **App ID** and **App secret**. The _App ID_ is the `clientId` in your Logto connector conifg and the _App secret_ is the `clientSecret`. -### Test sign-in with Facebook's test users +## Compose the connector JSON \{#compose-the-connector-json} + +1. In the Facebook app dashboard page, click the sidebar -> "Settings" -> "Basic". +2. You will see the "App ID" and "App secret" on the panel. +3. Click the "Show" button following the App secret input box to copy its content. +4. Fill out the Logto connector settings: + - Fill out the `clientId` field with the string from _App ID_. + - Fill out the `clientSecret` field with the string from _App secret_. + - Fill out the `scope` field with a comma or space separated list of [permissions](https://developers.facebook.com/docs/permissions/reference) in string. If you do not specify a scope, the default scope is `email,public_profile`. + +## Test sign-in with Facebook's test users \{#test-sign-in-with-facebooks-test-users} You can use the accounts of the test, developer, and admin users to test sign-in with the related app under both development and live [app modes](https://developers.facebook.com/docs/development/build-and-test/app-modes). -You can also set the app to "live mode" by [switching modes](https://developers.facebook.com/docs/development/build-and-test/app-modes#switching-modes) so that any Facebook user can sign in with the app. +You can also [take the app live](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode) directly so that any Facebook user can sign in with the app. - In the app dashboard page, click the sidebar -> "Roles" -> "Test Users". - Click the "Create test users" button to create a testing user. - Click the "Options" button of the existing test user, and you will see more operations, e.g., "Change name and password". -### Publish Facebook sign-in settings +## Publish Facebook sign-in settings \{#publish-facebook-sign-in-settings} Usually, only the test, admin, and developer users can sign in with the related app under [development mode](https://developers.facebook.com/docs/development/build-and-test/app-modes#development-mode). -To enable normal Facebook users sign-in with the app in the production environment, you may need to switch your Facebook app to _[live mode](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_, depending on the app type. -E.g., the pure _business type_ app doesn't have the "live" switch button, but it won't block you from using it. +To enable normal Facebook users sign-in with the app in the production environment, you maybe need to switch your Facebook app to _[live mode](https://developers.facebook.com/docs/development/build-and-test/app-modes#live-mode)_, depending on the app type. +E.g., the pure _business type_ app doesn't have the "live" switch button, but it won't block your use. 1. In the Facebook app dashboard page, click the sidebar -> "Settings" -> "Basic". 2. Fill out the "Privacy Policy URL" and "User data deletion" fields on the panel if required. 3. Click the "Save changes" button at the bottom right corner. 4. Click the "Live" switch button on the app top bar. -### References - -#### Config types +## Config types \{#config-types} | Name | Type | | ------------ | ------ | | clientId | string | | clientSecret | string | - -#### Facebook developer docs - -- [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) +| scope | string | diff --git a/docs/integrations/social/github/README.mdx b/docs/integrations/social/github/README.mdx index 4b5e094805f..beb0d0ddaa8 100644 --- a/docs/integrations/social/github/README.mdx +++ b/docs/integrations/social/github/README.mdx @@ -4,10 +4,13 @@ sidebar_label: GitHub sidebar_custom_props: darkLogoFilename: 'github-dark.svg' description: GitHub is an online community for software development and version control. +tutorial_config_name: GitHub OAuth app --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with GitHub The official Logto connector for GitHub social sign-in. @@ -18,43 +21,7 @@ The official Logto connector for GitHub social sign-in. The GitHub connector enables end-users to sign in to your application using their own GitHub accounts via GitHub OAuth 2.0 authentication protocol. -## Sign in with GitHub account \{#sign-in-with-github-account} - -Go to the [GitHub website](https://github.com/) and sign in with your GitHub account. You may register a new account if you don't have one. - -## Create and configure OAuth app \{#create-and-configure-oauth-app} - -Follow the [creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) guide, and register a new application. - -Name your new OAuth application in **Application name** and fill up **Homepage URL** of the app. -You can leave **Application description** field blank and customize **Authorization callback URL** as `${your_logto_origin}/callback/${connector_id}`. The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. - -:::note - -If you encounter the error message "The redirect_uri MUST match the registered callback URL for this application." when logging in, try aligning the Authorization Callback URL of your GitHub OAuth App and your Logto App's redirect URL (of course, including the protocol) to resolve the issue. - -::: - -We suggest not to check the box before **Enable Device Flow**, or users who sign in with GitHub on mobile devices must confirm the initial sign-in action in the GitHub app. Many GitHub users do not install the GitHub mobile app on their phones, which could block the sign-in flow. Please ignore our suggestion if you are expecting end-users to confirm their sign-in flow. See details of [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). - -## Managing OAuth apps \{#managing-oauth-apps} - -Go to the [OAuth Apps page](https://github.com/settings/developers) and you can add, edit or delete existing OAuth apps. -You can also find `Client ID` and generate `Client secrets` in OAuth app detail pages. - -## Configure your connector \{#configure-your-connector} - -Fill out the `clientId` and `clientSecret` field with _Client ID_ and _Client Secret_ you've got from OAuth app detail pages mentioned in the previous section. - -`scope` is a space-delimited list of [scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). If not provided, scope defaults to be `read:user`. - -### Config types \{#config-types} - -| Name | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | + ## Test GitHub connector \{#test-github-connector} diff --git a/tutorial/build-with-logto/_connector-github.mdx b/docs/integrations/social/github/_integration.mdx similarity index 60% rename from tutorial/build-with-logto/_connector-github.mdx rename to docs/integrations/social/github/_integration.mdx index 6dcafa4768f..ad8f09df8da 100644 --- a/tutorial/build-with-logto/_connector-github.mdx +++ b/docs/integrations/social/github/_integration.mdx @@ -1,39 +1,37 @@ -### Sign in with GitHub account +### Sign in with GitHub account \{#sign-in-with-github-account} Go to the [GitHub website](https://github.com/) and sign in with your GitHub account. You may register a new account if you don't have one. -### Create and configure OAuth app +### Create and configure OAuth app \{#create-and-configure-oauth-app} Follow the [creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) guide, and register a new application. Name your new OAuth application in **Application name** and fill up **Homepage URL** of the app. You can leave **Application description** field blank and customize **Authorization callback URL** as `${your_logto_origin}/callback/${connector_id}`. The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. -> Note: If you encounter the error message "The redirect_uri MUST match the registered callback URL for this application." when logging in, try aligning the Authorization Callback URL of your GitHub OAuth App and your Logto App's redirect URL (of course, including the protocol) to resolve the issue. +:::note + +If you encounter the error message "The redirect_uri MUST match the registered callback URL for this application." when logging in, try aligning the Authorization Callback URL of your GitHub OAuth App and your Logto App's redirect URL (of course, including the protocol) to resolve the issue. + +::: We suggest not to check the box before **Enable Device Flow**, or users who sign in with GitHub on mobile devices must confirm the initial sign-in action in the GitHub app. Many GitHub users do not install the GitHub mobile app on their phones, which could block the sign-in flow. Please ignore our suggestion if you are expecting end-users to confirm their sign-in flow. See details of [device flow](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow). -### Managing OAuth apps +### Managing OAuth apps \{#managing-oauth-apps} Go to the [OAuth Apps page](https://github.com/settings/developers) and you can add, edit or delete existing OAuth apps. You can also find `Client ID` and generate `Client secrets` in OAuth app detail pages. -### Compose the connector JSON - -Let's go back to Logto. Fill out the `clientId` and `clientSecret` field with _Client ID_ and _Client Secret_ you've got from OAuth app detail pages mentioned in the previous section. +### Configure your connector \{#configure-your-connector} -Here is an example of GitHub connector config JSON. +Fill out the `clientId` and `clientSecret` field with _Client ID_ and _Client Secret_ you've got from OAuth app detail pages mentioned in the previous section. -```json -{ - "clientID": "", - "clientSecret": "" -} -``` +`scope` is a space-delimited list of [scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). If not provided, scope defaults to be `read:user`. -#### Config types +### Config types \{#config-types} | Name | Type | | ------------ | ------ | | clientId | string | | clientSecret | string | +| scope | string | diff --git a/docs/integrations/social/google/README.mdx b/docs/integrations/social/google/README.mdx index c07ad75e427..943051abecc 100644 --- a/docs/integrations/social/google/README.mdx +++ b/docs/integrations/social/google/README.mdx @@ -3,99 +3,20 @@ slug: /integrations/google sidebar_label: Google sidebar_custom_props: description: Google is a principal search engine technology and email service provider. +tutorial_config_name: Google OAuth app --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with Google The Google connector provides a succinct way for your application to use Google’s OAuth 2.0 authentication system. -## Set up a project in the Google API Console \{#set-up-a-project-in-the-google-api-console} - -- Visit the [Google API Console](https://console.developers.google.com) and sign in with your Google account. -- Click the **Select a project** button on the top menu bar, and click the **New Project** button to create a project. -- In your newly created project, click the **APIs & Services** to enter the **APIs & Services** menu. - -## Configure your consent screen \{#configure-your-consent-screen} - -### Configure and register your application \{#configure-and-register-your-application} - -- On the left **APIs & Services** menu, click the **OAuth consent screen** button. -- Choose the **User Type** you want, and click the **Create** button. (Note: If you select **External** as your **User Type**, you will need to add test users later.) - -Now you will be on the **Edit app registration** page. - -### Edit app registration \{#edit-app-registration} - -#### Config OAuth consent screen \{#config-oauth-consent-screen} - -- Follow the instructions to fill out the **OAuth consent screen** form. -- Click **SAVE AND CONTINUE** to continue. - -#### Config scopes \{#config-scopes} - -- Click **ADD OR REMOVE SCOPES** and select `../auth/userinfo.email`, `../auth/userinfo.profile` and `openid` in the popup drawer, and click **UPDATE** to finish. It is recommended that you consider adding all the scopes you may use, otherwise some scopes you added in the configuration may not work. -- Fill out the form as you need. -- Click **SAVE AND CONTINUE** to continue. - -#### Add test users (External user type only) \{#add-test-users-external-user-type-only} - -- Click **ADD USERS** and add test users to allow these users to access your application while testing. -- Click **SAVE AND CONTINUE** to continue. - -Now you should have the Google OAuth 2.0 consent screen configured. - -## Obtain OAuth 2.0 credentials \{#obtain-oauth-20-credentials} - -- On the left **APIs & Services** menu, click the **Credentials** button. -- On the **Credentials** page, click the **+ CREATE CREDENTIALS** button on the top menu bar, and select **OAuth client ID**. -- On the **Create OAuth client ID** page, select **Web application** as the application type. -- Fill out the basic information for your application. -- Click **+ Add URI** to add an authorized domain to the **Authorized JavaScript origins** section. This is the domain that your logto authorization page will be served from. In our case, this will be `${your_logto_origin}`. e.g.`https://logto.dev`. -- Click **+ Add URI** in the \***\*Authorized redirect URIs\*\*** section to set up the \***\*Authorized redirect URIs\*\***, which redirect the user to the application after logging in. In our case, this will be `${your_logto_endpoint}/callback/${connector_id}`. e.g. `https://logto.dev/callback/${connector_id}`. The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. -- Click **Create** to finish and then you will get the **Client ID** and **Client Secret**. - -## Configure your connector \{#configure-your-connector} - -Fill out the `clientId` and `clientSecret` field with _Client ID_ and _Client Secret_ you've got from OAuth app detail pages mentioned in the previous section. - -`scope` is a space-delimited list of [scopes](https://developers.google.com/identity/protocols/oauth2/scopes). If not provided, scope defaults to be `openid profile email`. - -`prompts` is an array of strings that specifies the type of user interaction that is required. The string can be one of the following values: - -- `none`: The authorization server does not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not pre-configured consent for the requested scopes. You can use none to check for existing authentication and/or consent. -- `consent`: The authorization server prompts the user for consent before returning information to the client. -- `select_account`: The authorization server prompts the user to select a user account. This allows a user who has multiple accounts at the authorization server to select amongst the multiple accounts that they may have current sessions for. - -### Config types \{#config-types} - -| Name | Type | -| ------------ | -------- | -| clientId | string | -| clientSecret | string | -| scope | string | -| prompts | string[] | - -## Enable Google One Tap \{#enable-google-one-tap} - -[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) is a secure and easy way to let users sign in to your website or app with their Google account. - -Once you have the Google connector set up, you'll see a card for Google One Tap in the connector details page. You can enable Google One Tap in your sign-up and sign-in pages by toggling the switch. - -When you enable Google One Tap, you can configure the following 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 click/tap 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. -- **Enable Upgraded One Tap UX on ITP browsers**: Enable the upgraded Google One Tap user experience on Intelligent Tracking Prevention (ITP) browsers. Please refer to [this page](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) for more information. - -:::note - -To enable Google One Tap in your website (beyond the Logto sign-in experience), this feature is under development. Please stay tuned for updates. - -::: + ## References \{#references} diff --git a/docs/integrations/social/google/_integration.mdx b/docs/integrations/social/google/_integration.mdx new file mode 100644 index 00000000000..d81d94209f3 --- /dev/null +++ b/docs/integrations/social/google/_integration.mdx @@ -0,0 +1,83 @@ +## Set up a project in the Google API Console \{#set-up-a-project-in-the-google-api-console} + +- Visit the [Google API Console](https://console.developers.google.com) and sign in with your Google account. +- Click the **Select a project** button on the top menu bar, and click the **New Project** button to create a project. +- In your newly created project, click the **APIs & Services** to enter the **APIs & Services** menu. + +## Configure your consent screen \{#configure-your-consent-screen} + +### Configure and register your application \{#configure-and-register-your-application} + +- On the left **APIs & Services** menu, click the **OAuth consent screen** button. +- Choose the **User Type** you want, and click the **Create** button. (Note: If you select **External** as your **User Type**, you will need to add test users later.) + +Now you will be on the **Edit app registration** page. + +### Edit app registration \{#edit-app-registration} + +#### Config OAuth consent screen \{#config-oauth-consent-screen} + +- Follow the instructions to fill out the **OAuth consent screen** form. +- Click **SAVE AND CONTINUE** to continue. + +#### Config scopes \{#config-scopes} + +- Click **ADD OR REMOVE SCOPES** and select `../auth/userinfo.email`, `../auth/userinfo.profile` and `openid` in the popup drawer, and click **UPDATE** to finish. It is recommended that you consider adding all the scopes you may use, otherwise some scopes you added in the configuration may not work. +- Fill out the form as you need. +- Click **SAVE AND CONTINUE** to continue. + +#### Add test users (External user type only) \{#add-test-users-external-user-type-only} + +- Click **ADD USERS** and add test users to allow these users to access your application while testing. +- Click **SAVE AND CONTINUE** to continue. + +Now you should have the Google OAuth 2.0 consent screen configured. + +## Obtain OAuth 2.0 credentials \{#obtain-oauth-20-credentials} + +- On the left **APIs & Services** menu, click the **Credentials** button. +- On the **Credentials** page, click the **+ CREATE CREDENTIALS** button on the top menu bar, and select **OAuth client ID**. +- On the **Create OAuth client ID** page, select **Web application** as the application type. +- Fill out the basic information for your application. +- Click **+ Add URI** to add an authorized domain to the **Authorized JavaScript origins** section. This is the domain that your logto authorization page will be served from. In our case, this will be `${your_logto_origin}`. e.g.`https://logto.dev`. +- Click **+ Add URI** in the \***\*Authorized redirect URIs\*\*** section to set up the \***\*Authorized redirect URIs\*\***, which redirect the user to the application after logging in. In our case, this will be `${your_logto_endpoint}/callback/${connector_id}`. e.g. `https://logto.dev/callback/${connector_id}`. The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. +- Click **Create** to finish and then you will get the **Client ID** and **Client Secret**. + +## Configure your connector \{#configure-your-connector} + +Fill out the `clientId` and `clientSecret` field with _Client ID_ and _Client Secret_ you've got from OAuth app detail pages mentioned in the previous section. + +`scope` is a space-delimited list of [scopes](https://developers.google.com/identity/protocols/oauth2/scopes). If not provided, scope defaults to be `openid profile email`. + +`prompts` is an array of strings that specifies the type of user interaction that is required. The string can be one of the following values: + +- `none`: The authorization server does not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not pre-configured consent for the requested scopes. You can use none to check for existing authentication and/or consent. +- `consent`: The authorization server prompts the user for consent before returning information to the client. +- `select_account`: The authorization server prompts the user to select a user account. This allows a user who has multiple accounts at the authorization server to select amongst the multiple accounts that they may have current sessions for. + +### Config types \{#config-types} + +| Name | Type | +| ------------ | -------- | +| clientId | string | +| clientSecret | string | +| scope | string | +| prompts | string[] | + +## Enable Google One Tap \{#enable-google-one-tap} + +[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) is a secure and easy way to let users sign in to your website or app with their Google account. + +Once you have the Google connector set up, you'll see a card for Google One Tap in the connector details page. You can enable Google One Tap in your sign-up and sign-in pages by toggling the switch. + +When you enable Google One Tap, you can configure the following 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 click/tap 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. +- **Enable Upgraded One Tap UX on ITP browsers**: Enable the upgraded Google One Tap user experience on Intelligent Tracking Prevention (ITP) browsers. Please refer to [this page](https://developers.google.com/identity/gsi/web/guides/features#upgraded_ux_on_itp_browsers) for more information. + +:::note + +To enable Google One Tap in your website (beyond the Logto sign-in experience), this feature is under development. Please stay tuned for updates. + +::: diff --git a/docs/integrations/social/hugging-face/README.mdx b/docs/integrations/social/hugging-face/README.mdx new file mode 100644 index 00000000000..1a333a402ad --- /dev/null +++ b/docs/integrations/social/hugging-face/README.mdx @@ -0,0 +1,33 @@ +--- +slug: /integrations/huggingface +sidebar_label: Hugging Face +sidebar_custom_props: + description: Hugging Face is a machine learning (ML) and data science platform and community that helps users build, deploy and train machine learning models. +tutorial_config_name: Hugging Face OAuth app +--- + +import GuideTip from '../../fragments/_guide-tip.mdx'; + +import Integration from './_integration.mdx'; + +# Set up social login with Hugging Face + +The official Logto connector for Hugging Face social sign-in. + + + +## Get started \{#get-started} + +The Hugging Face connector enables end-users to sign in to your application using their own Hugging Face accounts via Hugging Face OAuth / OpenID connect flow. + + + +## Test Hugging Face connector \{#test-hugging-face-connector} + +That's it. The Hugging Face connector should be available now. Don't forget to [Enable social connector in sign-in experience](/connectors/social-connectors/#enable-social-sign-in). + +## Reference \{#reference} + + + Hugging Face - Sign in with Hugging Face + diff --git a/tutorial/build-with-logto/_connector-hugging-face.mdx b/docs/integrations/social/hugging-face/_integration.mdx similarity index 80% rename from tutorial/build-with-logto/_connector-hugging-face.mdx rename to docs/integrations/social/hugging-face/_integration.mdx index 9c51c78c0a2..045e211edaf 100644 --- a/tutorial/build-with-logto/_connector-hugging-face.mdx +++ b/docs/integrations/social/hugging-face/_integration.mdx @@ -1,8 +1,8 @@ -## Sign in with Hugging Face account +## Sign in with Hugging Face account \{#sign-in-with-hugging-face-account} Go to the [Hugging Face website](https://huggingface.co/) and sign in with your Hugging Face account. You may register a new account if you don't have one. -## Create an OAuth app in the Hugging Face +## Create an OAuth app in the Hugging Face \{#create-an-oauth-app-in-the-hugging-face} Follow the [Creating an oauth app](https://huggingface.co/docs/hub/en/oauth#creating-an-oauth-app) guide, and register a new application. @@ -14,18 +14,18 @@ In the creation process, you will need to provide the following information: - **Scopes**: The scopes allowed for the OAuth app. For Hugging Face connector, usually use `profile` to get the user's profile information and `email` to get the user's email address. Ensure these scopes are allowed in your Hugging Face OAuth app if you want to use them. - **Redirect URI**: The URL to redirect the user to after they have authenticated. You can find the redirect URI in the Logto Admin Console when you're creating a Hugging Face connector or in the created Hugging Face connector details page. -## Managing Hugging Face OAuth apps +## Managing Hugging Face OAuth apps \{#managing-hugging-face-oauth-apps} Go to the [Connected Applications](https://huggingface.co/settings/connected-applications) page, you can add, edit or delete existing OAuth apps. You can also find `Client ID` and generate `App secrets` in corresponding OAuth app settings pages. -## Configure your connector +## Configure your connector \{#configure-your-connector} -Go back to Logto Admin Console And Fill out the `clientId` and `clientSecret` field with _Client ID_ and _App Secret_ you've got from OAuth app detail pages mentioned in the previous section. +Fill out the `clientId` and `clientSecret` field with _Client ID_ and _App Secret_ you've got from OAuth app detail pages mentioned in the previous section. `scope` is a space-delimited list of [Hugging Face supported scopes](https://huggingface.co/docs/hub/en/oauth#currently-supported-scopes). If not provided, scope defaults to be `profile`. For Hugging Face connector, the scope you may want to use is `profile` and `email`. `profile` scope is required to get the user's profile information, and `email` scope is required to get the user's email address. Ensure you have allowed these scopes in your Hugging Face OAuth app (configured in [Create an OAuth app in the Hugging Face](#create-an-oauth-app-in-the-hugging-face) section). -### Config types +### Config types \{#config-types} | Name | Type | | ------------ | ------ | diff --git a/docs/integrations/social/huggingface/README.mdx b/docs/integrations/social/huggingface/README.mdx deleted file mode 100644 index 2685fd97201..00000000000 --- a/docs/integrations/social/huggingface/README.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -slug: /integrations/huggingface -sidebar_label: Hugging Face -sidebar_custom_props: - description: Hugging Face is a machine learning (ML) and data science platform and community that helps users build, deploy and train machine learning models. ---- - -import GuideTip from '../../fragments/_guide-tip.mdx'; - -# Set up social login with Hugging Face - -The official Logto connector for Hugging Face social sign-in. - - - -## Get started \{#get-started} - -The Hugging Face connector enables end-users to sign in to your application using their own Hugging Face accounts via Hugging Face OAuth / OpenID connect flow. - -## Sign in with Hugging Face account \{#sign-in-with-hugging-face-account} - -Go to the [Hugging Face website](https://huggingface.co/) and sign in with your Hugging Face account. You may register a new account if you don't have one. - -## Create an OAuth app in the Hugging Face \{#create-an-oauth-app-in-the-hugging-face} - -Follow the [Creating an oauth app](https://huggingface.co/docs/hub/en/oauth#creating-an-oauth-app) guide, and register a new application. - -In the creation process, you will need to provide the following information: - -- **Application Name**: The name of your application. -- **Homepage URL**: The URL of your application's homepage or landing page. -- **Logo URL**: The URL of your application's logo. -- **Scopes**: The scopes allowed for the OAuth app. For Hugging Face connector, usually use `profile` to get the user's profile information and `email` to get the user's email address. Ensure these scopes are allowed in your Hugging Face OAuth app if you want to use them. -- **Redirect URI**: The URL to redirect the user to after they have authenticated. You can find the redirect URI in the Logto Admin Console when you're creating a Hugging Face connector or in the created Hugging Face connector details page. - -## Managing Hugging Face OAuth apps \{#managing-hugging-face-oauth-apps} - -Go to the [Connected Applications](https://huggingface.co/settings/connected-applications) page, you can add, edit or delete existing OAuth apps. -You can also find `Client ID` and generate `App secrets` in corresponding OAuth app settings pages. - -## Configure your connector \{#configure-your-connector} - -Fill out the `clientId` and `clientSecret` field with _Client ID_ and _App Secret_ you've got from OAuth app detail pages mentioned in the previous section. - -`scope` is a space-delimited list of [Hugging Face supported scopes](https://huggingface.co/docs/hub/en/oauth#currently-supported-scopes). If not provided, scope defaults to be `profile`. For Hugging Face connector, the scope you may want to use is `profile` and `email`. `profile` scope is required to get the user's profile information, and `email` scope is required to get the user's email address. Ensure you have allowed these scopes in your Hugging Face OAuth app (configured in [Create an OAuth app in the Hugging Face](#create-an-oauth-app-in-the-hugging-face) section). - -### Config types \{#config-types} - -| Name | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | -| scope | string | - -## Test Hugging Face connector \{#test-hugging-face-connector} - -That's it. The Hugging Face connector should be available now. Don't forget to [Enable social connector in sign-in experience](/connectors/social-connectors/#enable-social-sign-in). - -## Reference \{#reference} - - - Hugging Face - Sign in with Hugging Face - diff --git a/docs/integrations/social/kakao/README.mdx b/docs/integrations/social/kakao/README.mdx index 663ecf2f9d8..99badfcb97c 100644 --- a/docs/integrations/social/kakao/README.mdx +++ b/docs/integrations/social/kakao/README.mdx @@ -3,57 +3,17 @@ slug: /integrations/kakao sidebar_label: Kakao sidebar_custom_props: description: Kakao is a famous social network service provider in South Korea. +tutorial_config_name: Kakao login --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with Kakao The Kakao connector provides a succinct way for your application to use Kakao’s OAuth 2.0 authentication system. -## Set up a project in the Kakao Devlopers Console \{#set-up-a-project-in-the-kakao-devlopers-console} - -- Visit the [Kakao Developers Console](https://developers.kakao.com/console/app) and sign in with your Kakao account. -- Click the **Add an application** to create new project or choose exist project. - -## Configure Kakao Login \{#configure-kakao-login} - -### Activate Kakao Login \{#activate-kakao-login} - -- Click the **Product Settings -> Kakao Login** from the menu. -- Turn on `Kakao Login Activation` -- Add below URL into `Redirect URI` - - `http(s)://YOUR_URL/callback/${connector_id}` (The `connector_id` can be found on the top bar of the Logto Admin Console connector details page.) - - (Please replace `YOUR_URL` with your `Logto` URL, and choose `http` or `https` on your situation.) - -### Privacy Setting \{#privacy-setting} - -- Click the **Product Settings -> Kakao Login -> Consent Item** from the menu. -- Change state of `Nickname`, `Profile image`, and `Email` to **Required consent** (You might not able to change `Email` to **Required consent** because of your project setting.) - -### Security Setting (Optional) \{#security-setting-optional} - -- Click the **Product Settings -> Kakao Login -> Security** from the menu. -- Click the `Client secret code` to generate secret code. -- Change `Activation state` to Enable. (If you enable it, `secret code` is necessary.) - -## Configure Logto \{#configure-logto} - -### Config types \{#config-types} - -| Name | Type | -| ------------ | ------- | -| clientId | string | -| clientSecret | string? | - -#### clientId \{#clientid} - -`clientId` is `REST API key` of your project. -(You can find it from `summary` of your project from Kakao developers console.) - -#### clientSeceret \{#clientseceret} - -`clientSecret` is `Secret Code` of your project. -(Please check [Security Setting (Optional)](#security-setting-optional)) + diff --git a/tutorial/build-with-logto/_connector-kakao.mdx b/docs/integrations/social/kakao/_integration.mdx similarity index 76% rename from tutorial/build-with-logto/_connector-kakao.mdx rename to docs/integrations/social/kakao/_integration.mdx index bacd8aa9447..14d7b73afe3 100644 --- a/tutorial/build-with-logto/_connector-kakao.mdx +++ b/docs/integrations/social/kakao/_integration.mdx @@ -1,11 +1,11 @@ -### Set up a project in the Kakao Devlopers Console +## Set up a project in the Kakao Devlopers Console \{#set-up-a-project-in-the-kakao-devlopers-console} - Visit the [Kakao Developers Console](https://developers.kakao.com/console/app) and sign in with your Kakao account. - Click the **Add an application** to create new project or choose exist project. -### Configure Kakao Login +## Configure Kakao Login \{#configure-kakao-login} -#### Activate Kakao Login +### Activate Kakao Login \{#activate-kakao-login} - Click the **Product Settings -> Kakao Login** from the menu. - Turn on `Kakao Login Activation` @@ -13,32 +13,32 @@ - `http(s)://YOUR_URL/callback/${connector_id}` (The `connector_id` can be found on the top bar of the Logto Admin Console connector details page.) - (Please replace `YOUR_URL` with your `Logto` URL, and choose `http` or `https` on your situation.) -#### Privacy Setting +### Privacy Setting \{#privacy-setting} - Click the **Product Settings -> Kakao Login -> Consent Item** from the menu. - Change state of `Nickname`, `Profile image`, and `Email` to **Required consent** (You might not able to change `Email` to **Required consent** because of your project setting.) -#### Security Setting (Optional) +### Security Setting (Optional) \{#security-setting-optional} - Click the **Product Settings -> Kakao Login -> Security** from the menu. - Click the `Client secret code` to generate secret code. - Change `Activation state` to Enable. (If you enable it, `secret code` is necessary.) -### Configure Logto +## Configure Logto \{#configure-logto} -#### Config types +### Config types \{#config-types} | Name | Type | | ------------ | ------- | | clientId | string | | clientSecret | string? | -#### clientId +#### clientId \{#clientid} `clientId` is `REST API key` of your project. (You can find it from `summary` of your project from Kakao developers console.) -#### clientSeceret +#### clientSeceret \{#clientseceret} `clientSecret` is `Secret Code` of your project. (Please check [Security Setting (Optional)](#security-setting-optional)) diff --git a/docs/integrations/social/naver/README.mdx b/docs/integrations/social/naver/README.mdx index 96cdeeb7290..fb801e96239 100644 --- a/docs/integrations/social/naver/README.mdx +++ b/docs/integrations/social/naver/README.mdx @@ -3,78 +3,17 @@ slug: /integrations/naver sidebar_label: Naver sidebar_custom_props: description: Naver is the most leading internet service provider in South Korea. +tutorial_config_name: Naver login --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with Naver The Naver connector provides a succinct way for your application to use Naver’s OAuth 2.0 authentication system. -## Developer Site Only Korean Support Now \{#developer-site-only-korean-support-now} - -Currently `Naver Developers` site only supports Korean. Please consider use a translator. - -## For the Production \{#for-the-production} - -- For the production, you have to get review from Naver team. - Otherwise, only registered users can sign in. - - You can add a tester from `맴버관리(Member Manage)` menu. -- To get a review, please check `애플리케이션 개발 상태(Application Devlopment Status)` - from `API 설정(API Setting)` from your application project setting. - -## Set up a project in the Naver Developers \{#set-up-a-project-in-the-naver-developers} - -- Visit the [Naver Developers](https://developers.naver.com/main/) and sign in with your Naver account. -- Click the **Application -> 어플리케이션 등록** from the menu to create new project. -- Follow the instruction below to create application. - -### Application Name (어플리케이션 이름) \{#application-name-어플리케이션-이름} - -- Type your application name on `어플리케이션 이름` (This name is shown while a user sign in.) - -### API Usage (사용 API) \{#api-usage-사용-api} - -- Choose `네이버 로그인(Naver Login)` for `사용 API(API Usage)` -- Check `이메일 주소(Email Address), 별명(Nickname), 프로필 사진(Profile Image)` as `필수(Neccessary)` from `권한(Role)` (You can check `추가(Add)` as optional these options, but you cannot get the information from the user.) - -### Sign in Open API Service Environment (로그인 오픈 API 서비스 환경) \{#sign-in-open-api-service-environment-로그인-오픈-api-서비스-환경} - -- For `로그인 오픈 API 서비스 환경(Sign in Open API Service Environment)`, add two environment `PC웹(PC Web)` and `모바일웹(Mobile Web)`. - -#### PC Web (PC 웹) \{#pc-web-pc-웹} - -- For `서비스 URL(Service URL)`, type `http(s)://YOUR_URL` (ex. https://logto.io) -- For `네이버 로그인(Naver Login) Callback URL`, type `http(s)://YOUR_URL/callback/${connector_id}` (e.g. https://logto.io/callback/${connector_id}) - -#### Mobile Web (Mobile 웹) \{#mobile-web-mobile-웹} - -- For `서비스 URL(Service URL)`, type `http(s)://YOUR_URL` (ex. https://logto.io) -- For `네이버 로그인(Naver Login) Callback URL`, type `http(s)://YOUR_URL/callback/${connector_id}` (e.g. https://logto.io/callback/${connector_id}) - -:::caution - -The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. - -::: - -## Configure Logto \{#configure-logto} - -### Config types \{#config-types} - -| Name | Type | -| ------------ | ------ | -| clientId | string | -| clientSecret | string | - -#### clientId \{#clientid} - -`clientId` is `Client ID` of your project. -(You can find it from `애플리케이션 정보(Application Info)` of your project from Naver developers.) - -#### clientSeceret \{#clientseceret} - -`clientSecret` is `Client Secret` of your project. -(You can find it from `애플리케이션 정보(Application Info)` of your project from Naver developers.) + diff --git a/tutorial/build-with-logto/_connector-naver.mdx b/docs/integrations/social/naver/_integration.mdx similarity index 65% rename from tutorial/build-with-logto/_connector-naver.mdx rename to docs/integrations/social/naver/_integration.mdx index 7acb548aa35..02576933e5e 100644 --- a/tutorial/build-with-logto/_connector-naver.mdx +++ b/docs/integrations/social/naver/_integration.mdx @@ -1,8 +1,8 @@ -### Developer Site Only Korean Support Now +## Developer Site Only Korean Support Now \{#developer-site-only-korean-support-now} Currently `Naver Developers` site only supports Korean. Please consider use a translator. -### For the Production +## For the Production \{#for-the-production} - For the production, you have to get review from Naver team. Otherwise, only registered users can sign in. @@ -10,54 +10,56 @@ Currently `Naver Developers` site only supports Korean. Please consider use a tr - To get a review, please check `애플리케이션 개발 상태(Application Devlopment Status)` from `API 설정(API Setting)` from your application project setting. -### Set up a project in the Naver Developers +## Set up a project in the Naver Developers \{#set-up-a-project-in-the-naver-developers} - Visit the [Naver Developers](https://developers.naver.com/main/) and sign in with your Naver account. - Click the **Application -> 어플리케이션 등록** from the menu to create new project. - Follow the instruction below to create application. -#### Application Name (어플리케이션 이름) +### Application Name (어플리케이션 이름) \{#application-name-어플리케이션-이름} - Type your application name on `어플리케이션 이름` (This name is shown while a user sign in.) -#### API Usage (사용 API) +### API Usage (사용 API) \{#api-usage-사용-api} - Choose `네이버 로그인(Naver Login)` for `사용 API(API Usage)` - Check `이메일 주소(Email Address), 별명(Nickname), 프로필 사진(Profile Image)` as `필수(Neccessary)` from `권한(Role)` (You can check `추가(Add)` as optional these options, but you cannot get the information from the user.) -#### Sign in Open API Service Environment (로그인 오픈 API 서비스 환경) +### Sign in Open API Service Environment (로그인 오픈 API 서비스 환경) \{#sign-in-open-api-service-environment-로그인-오픈-api-서비스-환경} - For `로그인 오픈 API 서비스 환경(Sign in Open API Service Environment)`, add two environment `PC웹(PC Web)` and `모바일웹(Mobile Web)`. -**PC Web (PC 웹)** +#### PC Web (PC 웹) \{#pc-web-pc-웹} - For `서비스 URL(Service URL)`, type `http(s)://YOUR_URL` (ex. https://logto.io) -- For `네이버 로그인(Naver Login) Callback URL`, type `http(s)://YOUR_URL/callback/connector_id` (e.g. https://logto.io/callback/connector_id) +- For `네이버 로그인(Naver Login) Callback URL`, type `http(s)://YOUR_URL/callback/${connector_id}` (e.g. https://logto.io/callback/${connector_id}) -**Mobile Web (Mobile 웹)** +#### Mobile Web (Mobile 웹) \{#mobile-web-mobile-웹} - For `서비스 URL(Service URL)`, type `http(s)://YOUR_URL` (ex. https://logto.io) -- For `네이버 로그인(Naver Login) Callback URL`, type `http(s)://YOUR_URL/callback/connector_id` (e.g. https://logto.io/callback/connector_id) +- For `네이버 로그인(Naver Login) Callback URL`, type `http(s)://YOUR_URL/callback/${connector_id}` (e.g. https://logto.io/callback/${connector_id}) -> ⚠️ **Caution** -> -> The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. +:::caution -### Configure Logto +The `connector_id` can be found on the top bar of the Logto Admin Console connector details page. -#### Config types +::: + +## Configure Logto \{#configure-logto} + +### Config types \{#config-types} | Name | Type | | ------------ | ------ | | clientId | string | | clientSecret | string | -#### clientId +#### clientId \{#clientid} `clientId` is `Client ID` of your project. (You can find it from `애플리케이션 정보(Application Info)` of your project from Naver developers.) -#### clientSeceret +#### clientSeceret \{#clientseceret} `clientSecret` is `Client Secret` of your project. (You can find it from `애플리케이션 정보(Application Info)` of your project from Naver developers.) diff --git a/docs/integrations/social/oauth2/README.mdx b/docs/integrations/social/oauth2/README.mdx index 3b448162941..36e0220c1ba 100644 --- a/docs/integrations/social/oauth2/README.mdx +++ b/docs/integrations/social/oauth2/README.mdx @@ -4,10 +4,14 @@ sidebar_label: OAuth 2.0 (Social) sidebar_custom_props: description: 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: Standard OAuth 2.0 app --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with OAuth 2.0 protocol The official Logto connector for OAuth 2.0 protocol. @@ -24,77 +28,7 @@ OAuth connector is a special kind of connector in Logto, you can add a few OAuth ::: -## Create your OAuth app \{#create-your-oauth-app} - -When you open this page, we believe you already know which social identity provider you want to connect to. The first thing to do is to confirm that the identity provider supports the OAuth protocol, which is a prerequisite for configuring a valid connector. Then, follow the identity provider's instructions to register and create the relevant app for OAuth authorization. - -## Configure your connector \{#configure-your-connector} - -We ONLY support "Authorization Code" grant type for security consideration and it can perfectly fit Logto's scenario. - -`clientId` and `clientSecret` can be found at your OAuth apps details page. - -_clientId_: The client ID is a unique identifier that identifies the client application during registration with the authorization server. This ID is used by the authorization server to verify the identity of the client application and to associate any authorized access tokens with that specific client application. - -_clientSecret_: The client secret is a confidential key that is issued to the client application by the authorization server during registration. The client application uses this secret key to authenticate itself with the authorization server when requesting access tokens. The client secret is considered confidential information and should be kept secure at all times. - -_tokenEndpointAuthMethod_: The token endpoint authentication method is used by the client application to authenticate itself with the authorization server when requesting access tokens. To discover supported methods, consult the `token_endpoint_auth_methods_supported` field available at the OAuth 2.0 service provider’s OpenID Connect discovery endpoint, or refer to the relevant documentation provided by the OAuth 2.0 service provider. - -_clientSecretJwtSigningAlgorithm (Optional)_: Only required when `tokenEndpointAuthMethod` is `client_secret_jwt`. The client secret JWT signing algorithm is used by the client application to sign the JWT that is sent to the authorization server during the token request. - -_scope_: The scope parameter is used to specify the set of resources and permissions that the client application is requesting access to. The scope parameter is typically defined as a space-separated list of values that represent specific permissions. For example, a scope value of "read write" might indicate that the client application is requesting read and write access to a user's data. - -You are expected to find `authorizationEndpoint`, `tokenEndpoint` and `userInfoEndpoint` in social vendor's documentation. - -_authenticationEndpoint_: This endpoint is used to initiate the authentication process. The authentication process typically involves the user logging in and granting authorization for the client application to access their resources. - -_tokenEndpoint_: This endpoint is used by the client application to obtain an access token that can be used to access the requested resources. The client application typically sends a request to the token endpoint with a grant type and authorization code to receive an access token. - -_userInfoEndpoint_: This endpoint is used by the client application to obtain additional information about the user, such as their fullname, email address or profile picture. The user info endpoint is typically accessed after the client application has obtained an access token from the token endpoint. - -Logto also provide a `profileMap` field that users can customize the mapping from the social vendors' profiles which are usually not standard. The keys are Logto's standard user profile field names and corresponding values should be social profiles' field names. In current stage, Logto only concern 'id', 'name', 'avatar', 'email' and 'phone' from social profile, only 'id' is required and others are optional fields. - -`responseType` and `grantType` can ONLY be FIXED values with authorization code grant type, so we make them optional and default values will be automatically filled. - -For example, you can find [Google user profile response](https://developers.google.com/identity/openid-connect/openid-connect#an-id-tokens-payload) and hence its `profileMap` should be like: - -```json -{ - "id": "sub", - "avatar": "picture" -} -``` - -:::note - -We provided an OPTIONAL `customConfig` key to put your customize parameters. -Each social identity provider could have their own variant on OAuth standard protocol. If your desired social identity provider strictly stick to OAuth standard protocol, the you do not need to care about `customConfig`. - -::: - -## Config types \{#config-types} - -| 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 | + ## Reference \{#reference} diff --git a/tutorial/build-with-logto/_connector-oauth2.mdx b/docs/integrations/social/oauth2/_integration.mdx similarity index 59% rename from tutorial/build-with-logto/_connector-oauth2.mdx rename to docs/integrations/social/oauth2/_integration.mdx index 9b51dbce88c..42b8dfa0cb3 100644 --- a/tutorial/build-with-logto/_connector-oauth2.mdx +++ b/docs/integrations/social/oauth2/_integration.mdx @@ -1,17 +1,21 @@ -### Create your OAuth 2.0 app +## Create your OAuth app \{#create-your-oauth-app} -When you open this page, we believe you already know which social identity provider you want to connect to. The first thing to do is to confirm that the identity provider supports the OAuth 2.0 protocol, which is a prerequisite for configuring a valid connector. Then, follow the identity provider's instructions to register and create the relevant app for OAuth 2.0 authorization. +When you open this page, we believe you already know which social identity provider you want to connect to. The first thing to do is to confirm that the identity provider supports the OAuth protocol, which is a prerequisite for configuring a valid connector. Then, follow the identity provider's instructions to register and create the relevant app for OAuth authorization. -### Configure your connector +## Configure your connector \{#configure-your-connector} We ONLY support "Authorization Code" grant type for security consideration and it can perfectly fit Logto's scenario. -`clientId` and `clientSecret` can be found at your OAuth 2.0 apps details page. +`clientId` and `clientSecret` can be found at your OAuth apps details page. _clientId_: The client ID is a unique identifier that identifies the client application during registration with the authorization server. This ID is used by the authorization server to verify the identity of the client application and to associate any authorized access tokens with that specific client application. _clientSecret_: The client secret is a confidential key that is issued to the client application by the authorization server during registration. The client application uses this secret key to authenticate itself with the authorization server when requesting access tokens. The client secret is considered confidential information and should be kept secure at all times. +_tokenEndpointAuthMethod_: The token endpoint authentication method is used by the client application to authenticate itself with the authorization server when requesting access tokens. To discover supported methods, consult the `token_endpoint_auth_methods_supported` field available at the OAuth 2.0 service provider’s OpenID Connect discovery endpoint, or refer to the relevant documentation provided by the OAuth 2.0 service provider. + +_clientSecretJwtSigningAlgorithm (Optional)_: Only required when `tokenEndpointAuthMethod` is `client_secret_jwt`. The client secret JWT signing algorithm is used by the client application to sign the JWT that is sent to the authorization server during the token request. + _scope_: The scope parameter is used to specify the set of resources and permissions that the client application is requesting access to. The scope parameter is typically defined as a space-separated list of values that represent specific permissions. For example, a scope value of "read write" might indicate that the client application is requesting read and write access to a user's data. You are expected to find `authorizationEndpoint`, `tokenEndpoint` and `userInfoEndpoint` in social vendor's documentation. @@ -35,26 +39,28 @@ For example, you can find [Google user profile response](https://developers.goog } ``` -> ℹ️ **Note** -> -> We provided an OPTIONAL `customConfig` key to put your customize parameters. -> Each social identity provider could have their own variant on OAuth 2.0 standard protocol. If your desired social identity provider strictly stick to OAuth 2.0 standard protocol, the you do not need to care about `customConfig`. - -### Config types - -| 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 | \{ [key: string]: string \} | false | -| profileMap | ProfileMap | false | +:::note + +We provided an OPTIONAL `customConfig` key to put your customize parameters. +Each social identity provider could have their own variant on OAuth standard protocol. If your desired social identity provider strictly stick to OAuth standard protocol, the you do not need to care about `customConfig`. + +::: + +## Config types \{#config-types} + +| 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 | | ----------------- | ------ | -------- | ------------- | @@ -63,7 +69,3 @@ For example, you can find [Google user profile response](https://developers.goog | avatar | string | false | avatar | | email | string | false | email | | phone | string | false | phone | - -### Reference - -- [The OAuth 2.0 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) diff --git a/docs/integrations/social/oidc/README.mdx b/docs/integrations/social/oidc/README.mdx index c944854c181..17217173992 100644 --- a/docs/integrations/social/oidc/README.mdx +++ b/docs/integrations/social/oidc/README.mdx @@ -3,10 +3,14 @@ slug: /integrations/oidc sidebar_label: OIDC (Social) sidebar_custom_props: description: OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. +tutorial_name: OIDC +tutorial_config_name: Standard OIDC app --- import GuideTip from '../../fragments/_guide-tip.mdx'; +import Integration from './_integration.mdx'; + # Set up social login with OpenID Connect (OIDC) The official Logto connector for OpenID Connect (OIDC) protocol. @@ -23,88 +27,4 @@ OIDC connector is a special kind of connector in Logto, you can add a few OIDC-b ::: -## Create your OIDC app \{#create-your-oidc-app} - -When you open this page, we believe you already know which social identity provider you want to connect to. The first thing to do is to confirm that the identity provider supports the OIDC protocol, which is a prerequisite for configuring a valid connector. Then, follow the identity provider's instructions to register and create the relevant app for OIDC authorization. - -## Configure your connector \{#configure-your-connector} - -We ONLY support "Authorization Code" grant type for security consideration and it can perfectly fit Logto's scenario. - -`clientId` and `clientSecret` can be found at your OIDC apps details page. - -_clientId_: The client ID is a unique identifier that identifies the client application during registration with the authorization server. This ID is used by the authorization server to verify the identity of the client application and to associate any authorized access tokens with that specific client application. - -_clientSecret_: The client secret is a confidential key that is issued to the client application by the authorization server during registration. The client application uses this secret key to authenticate itself with the authorization server when requesting access tokens. The client secret is considered confidential information and should be kept secure at all times. - -_tokenEndpointAuthMethod_: The token endpoint authentication method is used by the client application to authenticate itself with the authorization server when requesting access tokens. To discover supported methods, consult the `token_endpoint_auth_methods_supported` field available at the OAuth 2.0 service provider’s OpenID Connect discovery endpoint, or refer to the relevant documentation provided by the OAuth 2.0 service provider. - -_clientSecretJwtSigningAlgorithm (Optional)_: Only required when `tokenEndpointAuthMethod` is `client_secret_jwt`. The client secret JWT signing algorithm is used by the client application to sign the JWT that is sent to the authorization server during the token request. - -_scope_: The scope parameter is used to specify the set of resources and permissions that the client application is requesting access to. The scope parameter is typically defined as a space-separated list of values that represent specific permissions. For example, a scope value of "read write" might indicate that the client application is requesting read and write access to a user's data. - -You are expected to find `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` and `issuer` as OpenID Provider's configuration information. They should be available in social vendor's documentation. - -_authenticationEndpoint_: This endpoint is used to initiate the authentication process. The authentication process typically involves the user logging in and granting authorization for the client application to access their resources. - -_tokenEndpoint_: This endpoint is used by the client application to obtain an id token that can be used to access the requested resources. The client application typically sends a request to the token endpoint with a grant type and authorization code to receive an id token. - -_jwksUri_: This is the URL endpoint where the JSON Web Key Set (JWKS) of the social identity provider (IdP for short) can be obtained. The JWKS is a set of cryptographic keys that the IdP uses to sign and verify JSON Web Tokens (JWTs) that are issued during the authentication process. The `jwksUri` is used by the relying party (RP) to obtain the public keys used by the IdP to sign the JWTs, so the RP can verify the authenticity and integrity of the JWTs received from the IdP. - -_issuer_: This is the unique identifier of the IdP that is used by the RP to verify the JWTs received from the IdP. It is included in the JWTs as the `iss` [claim](https://www.rfc-editor.org/rfc/rfc7519#section-4) (Id token is always a JWT). The issuer value should match the URL of the IdP's authorization server, and it should be a URI that the RP trusts. When the RP receives a JWT, it checks the `iss` claim to ensure that it was issued by a trusted IdP, and that the JWT is intended for use with the RP. - -Together, `jwksUri` and `issuer` provide a secure mechanism for the RP to verify the identity of the end-user during the authentication process. By using the public keys obtained from the `jwksUri`, the RP can verify the authenticity and integrity of the JWTs issued by the IdP. The issuer value ensures that the RP only accepts JWTs that were issued by a trusted IdP, and that the JWTs are intended for use with the RP. - -Since an authentication request is always required, an `authRequestOptionalConfig` is provided to wrap all optional configs, you can find details on [OIDC Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). You may also find that `nonce` is missing in this config. Since `nonce` should identical for each request, we put the generation of `nonce` in code implementation. So do not worry about it! Previously mentioned `jwksUri` and `issuer` are also included in `idTokenVerificationConfig`. - -You may be curious as to why a standard OIDC protocol supports both the implicit and hybrid flows, yet the Logto connector only supports the authorization flow. It has been determined that the implicit and hybrid flows are less secure than the authorization flow. Due to Logto's focus on security, it only supports the authorization flow for the highest level of security for its users, despite its slightly less convenient nature. - -`responseType` and `grantType` can ONLY be FIXED values with "Authorization Code" flow, so we make them optional and default values will be automatically filled. - -:::note - -For all flow types, we provided an OPTIONAL `customConfig` key to put your customize parameters. -Each social identity provider could have their own variant on OIDC standard protocol. If your desired social identity provider strictly stick to OIDC standard protocol, the you do not need to care about `customConfig`. - -::: - -## Config types \{#config-types} - -| Name | Type | Required | -| ------------------------- | ------------------------- | -------- | -| scope | string | True | -| clientId | string | True | -| clientSecret | string | True | -| authorizationEndpoint | string | True | -| tokenEndpoint | string | True | -| idTokenVerificationConfig | IdTokenVerificationConfig | True | -| authRequestOptionalConfig | AuthRequestOptionalConfig | False | -| customConfig | Record\ | False | - -| AuthRequestOptionalConfig properties | Type | Required | -| ------------------------------------ | ------ | -------- | -| 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 properties | Type | Required | -| ------------------------------------ | ---------------------------------- | -------- | -| 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 | - -See [here](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) to find more details about `IdTokenVerificationConfig`. + diff --git a/tutorial/build-with-logto/_connector-oidc.mdx b/docs/integrations/social/oidc/_integration.mdx similarity index 74% rename from tutorial/build-with-logto/_connector-oidc.mdx rename to docs/integrations/social/oidc/_integration.mdx index 3c3c3c01ca0..425798ed329 100644 --- a/tutorial/build-with-logto/_connector-oidc.mdx +++ b/docs/integrations/social/oidc/_integration.mdx @@ -1,8 +1,8 @@ -### Create your OIDC app +## Create your OIDC app \{#create-your-oidc-app} When you open this page, we believe you already know which social identity provider you want to connect to. The first thing to do is to confirm that the identity provider supports the OIDC protocol, which is a prerequisite for configuring a valid connector. Then, follow the identity provider's instructions to register and create the relevant app for OIDC authorization. -### Configure your connector +## Configure your connector \{#configure-your-connector} We ONLY support "Authorization Code" grant type for security consideration and it can perfectly fit Logto's scenario. @@ -12,6 +12,10 @@ _clientId_: The client ID is a unique identifier that identifies the client appl _clientSecret_: The client secret is a confidential key that is issued to the client application by the authorization server during registration. The client application uses this secret key to authenticate itself with the authorization server when requesting access tokens. The client secret is considered confidential information and should be kept secure at all times. +_tokenEndpointAuthMethod_: The token endpoint authentication method is used by the client application to authenticate itself with the authorization server when requesting access tokens. To discover supported methods, consult the `token_endpoint_auth_methods_supported` field available at the OAuth 2.0 service provider’s OpenID Connect discovery endpoint, or refer to the relevant documentation provided by the OAuth 2.0 service provider. + +_clientSecretJwtSigningAlgorithm (Optional)_: Only required when `tokenEndpointAuthMethod` is `client_secret_jwt`. The client secret JWT signing algorithm is used by the client application to sign the JWT that is sent to the authorization server during the token request. + _scope_: The scope parameter is used to specify the set of resources and permissions that the client application is requesting access to. The scope parameter is typically defined as a space-separated list of values that represent specific permissions. For example, a scope value of "read write" might indicate that the client application is requesting read and write access to a user's data. You are expected to find `authorizationEndpoint`, `tokenEndpoint`, `jwksUri` and `issuer` as OpenID Provider's configuration information. They should be available in social vendor's documentation. @@ -32,23 +36,25 @@ You may be curious as to why a standard OIDC protocol supports both the implicit `responseType` and `grantType` can ONLY be FIXED values with "Authorization Code" flow, so we make them optional and default values will be automatically filled. -> ℹ️ **Note** -> -> For all flow types, we provided an OPTIONAL `customConfig` key to put your customize parameters. -> Each social identity provider could have their own variant on OIDC standard protocol. If your desired social identity provider strictly stick to OIDC standard protocol, the you do not need to care about `customConfig`. +:::note + +For all flow types, we provided an OPTIONAL `customConfig` key to put your customize parameters. +Each social identity provider could have their own variant on OIDC standard protocol. If your desired social identity provider strictly stick to OIDC standard protocol, the you do not need to care about `customConfig`. + +::: -### Config types +## Config types \{#config-types} -| Name | Type | Required | -| ------------------------- | --------------------------- | -------- | -| scope | string | True | -| clientId | string | True | -| clientSecret | string | True | -| authorizationEndpoint | string | True | -| tokenEndpoint | string | True | -| idTokenVerificationConfig | IdTokenVerificationConfig | True | -| authRequestOptionalConfig | AuthRequestOptionalConfig | False | -| customConfig | \{ [key: string]: string \} | False | +| Name | Type | Required | +| ------------------------- | ------------------------- | -------- | +| scope | string | True | +| clientId | string | True | +| clientSecret | string | True | +| authorizationEndpoint | string | True | +| tokenEndpoint | string | True | +| idTokenVerificationConfig | IdTokenVerificationConfig | True | +| authRequestOptionalConfig | AuthRequestOptionalConfig | False | +| customConfig | Record\ | False | | AuthRequestOptionalConfig properties | Type | Required | | ------------------------------------ | ------ | -------- | @@ -63,17 +69,17 @@ You may be curious as to why a standard OIDC protocol supports both the implicit | loginHint | string | False | | acrValues | string | False | -| IdTokenVerificationConfig properties | Type | Required | -| ------------------------------------ | -------------------------------------- | -------- | -| jwksUri | string | True | -| issuer | string \| string[] | False | -| audience | string \| string[] | False | -| algorithms | string[] | False | -| clockTolerance | string \| number | False | -| crit | \{ [key: string]: string \| boolean \} | False | -| currentDate | Date | False | -| maxTokenAge | string \| number | False | -| subject | string | False | -| typ | string | False | +| IdTokenVerificationConfig properties | Type | Required | +| ------------------------------------ | ---------------------------------- | -------- | +| 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 | See [here](https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md) to find more details about `IdTokenVerificationConfig`. diff --git a/docs/integrations/social/saml/README.mdx b/docs/integrations/social/saml/README.mdx new file mode 100644 index 00000000000..352aa4d36e6 --- /dev/null +++ b/docs/integrations/social/saml/README.mdx @@ -0,0 +1,31 @@ +--- +unlisted: true +slug: /integrations/saml +sidebar_label: SAML (Social) +sidebar_custom_props: + description: SAML is an open protocol for authentication that is designed to be simple and secure. +tutorial_name: SAML +tutorial_config_name: Standard SAML app +--- + +import GuideTip from '../../fragments/_guide-tip.mdx'; + +import Integration from './_integration.mdx'; + +# Set up social login with SAML + +The official Logto connector for SAML protocol. + + + +## Get started \{#get-started} + +The SAML connector enables Logto's connection to an arbitrary social identity provider that supports SAML protocol. + +:::note + +SAML connector is a special kind of connector in Logto, you can add a few SAML-based connector. + +::: + + diff --git a/tutorial/build-with-logto/_connector-saml.mdx b/docs/integrations/social/saml/_integration.mdx similarity index 89% rename from tutorial/build-with-logto/_connector-saml.mdx rename to docs/integrations/social/saml/_integration.mdx index f7e9e2d43dd..a44c660fd65 100644 --- a/tutorial/build-with-logto/_connector-saml.mdx +++ b/docs/integrations/social/saml/_integration.mdx @@ -1,3 +1,5 @@ +{/* Used to generate saml social tutorials, for backwards compatibility purposes only. */} + ### Create social IdP's account and register SAML application (IdP) Let's go through configurations of SAML connector. @@ -8,9 +10,9 @@ If your IdP mandate the encryption of SAML assertion and receiving of signed aut You also need to configure the ACS (Assertion Consumer Service) URL as `${your_logto_origin}/api/authn/saml/${connector_id}` to handle IdP's SAML assertion. Where you can find your `connectorId` at SAML connector's details page in Logto's Admin Console. -> ℹ️ **Note** -> -> Per current Logto's design, we only support Redirect-binding for sending authentication request and POST-binding for receiving SAML assertion. Although this sounds not cool, but we believe that the current design can handle most of your use cases. If you have any problems, feel free to reach out! +:::note +Per current Logto's design, we only support Redirect-binding for sending authentication request and POST-binding for receiving SAML assertion. Although this sounds not cool, but we believe that the current design can handle most of your use cases. If you have any problems, feel free to reach out! +::: ### Configure SAML connector (SP) @@ -34,11 +36,13 @@ The content of the certificate comes with `-----BEGIN CERTIFICATE-----` header a The field is used to place contents from your IdP metadata XML file. -> ℹ️ **Note** -> -> The XML parser we are using does not support customized namespace. -> If the IdP metadata comes with namespace, you should manually remove them. -> For namespace of XML file, see [reference](http://www.xmlmaster.org/en/article/d01/c10/). +:::note + +The XML parser we are using does not support customized namespace. +If the IdP metadata comes with namespace, you should manually remove them. +For namespace of XML file, see [reference](http://www.xmlmaster.org/en/article/d01/c10/). + +::: #### assertionConsumerServiceUrl `Required` @@ -52,10 +56,12 @@ The boolean value that controls whether SAML authentication request should be si `encryptAssertion` is a boolean value that indicates if IdP will encrypt SAML assertion, with default value `false`. -> ℹ️ **Note** -> -> `signAuthnRequest` and `encryptAssertion` attributes should align with corresponding parameters of IdP setting, otherwise error will be thrown to show that configuration does not match. -> All SAML responses need to be signed. +:::note + +The `signAuthnRequest` and `encryptAssertion` attributes should align with corresponding parameters of IdP setting, otherwise error will be thrown to show that configuration does not match. +All SAML responses need to be signed. + +::: #### requestSignatureAlgorithm @@ -81,16 +87,18 @@ If `signAuthnRequest` is `true`, the corresponding certificate generated from `p If `encryptAssertion` is `true`, the corresponding certificate generated from `encPrivateKey` is required by IdP for encrypting SAML assertion. -> ℹ️ **Note** -> -> For keys and certificates generation, `openssl` is a wonderful tool. Here is sample command line that might be helpful: -> -> ```bash -> openssl genrsa -passout pass:${privateKeyPassword} -out ${encryptPrivateKeyFilename}.pem 4096 -> openssl req -new -x509 -key ${encryptPrivateKeyFilename}.pem -out ${encryptionCertificateFilename}.cer -days 3650 -> ``` -> -> `privateKey` and `encPrivateKey` files are enforced to be encoded in `pkcs1` scheme as pem string, which means the private key files should start with `-----BEGIN RSA PRIVATE KEY-----` and end with `-----END RSA PRIVATE KEY-----`. +:::note + +For keys and certificates generation, `openssl` is a wonderful tool. Here is sample command line that might be helpful: + +```bash +openssl genrsa -passout pass:${privateKeyPassword} -out ${encryptPrivateKeyFilename}.pem 4096 +openssl req -new -x509 -key ${encryptPrivateKeyFilename}.pem -out ${encryptionCertificateFilename}.cer -days 3650 +``` + +`privateKey` and `encPrivateKey` files are enforced to be encoded in `pkcs1` scheme as pem string, which means the private key files should start with `-----BEGIN RSA PRIVATE KEY-----` and end with `-----END RSA PRIVATE KEY-----`. + +::: #### nameIDFormat diff --git a/docs/quick-starts/fragments/_checkpoint-test-your-application.md b/docs/quick-starts/fragments/_checkpoint-test-your-application.md index e8d1c7a7d22..027a87d2f58 100644 --- a/docs/quick-starts/fragments/_checkpoint-test-your-application.md +++ b/docs/quick-starts/fragments/_checkpoint-test-your-application.md @@ -5,4 +5,4 @@ Now, you can test your application: 1. Run your application, you will see the sign-in button. 2. Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page. 3. After you signed in, you will be redirected back to your application and see the sign-out button. -4. Click the sign-out button to clear local storage and sign out. +4. Click the sign-out button to clear token storage and sign out. diff --git a/docs/quick-starts/framework/android/README.mdx b/docs/quick-starts/framework/android/README.mdx index f1ad44bf49b..16f04276e2e 100644 --- a/docs/quick-starts/framework/android/README.mdx +++ b/docs/quick-starts/framework/android/README.mdx @@ -3,6 +3,10 @@ slug: /quick-starts/android sidebar_label: Android (Kotlin / Java) sidebar_custom_props: description: Android integration guide. +language: kotlin/java +official_link: https://developer.android.com +app_type: Native app +framework: Android (Kotlin) / Android (Java) --- import CodeBlock from '@theme/CodeBlock'; diff --git a/docs/quick-starts/framework/android/_for-tutorial.mdx b/docs/quick-starts/framework/android/_for-tutorial.mdx new file mode 100644 index 00000000000..6e3a7fbe0e0 --- /dev/null +++ b/docs/quick-starts/framework/android/_for-tutorial.mdx @@ -0,0 +1,31 @@ +import redirectUriFigure from '../../assets/android-redirect-uri.png'; +import Checkpoint from '../../fragments/_checkpoint-test-your-application.md'; +import ConfigureRedirectUri from '../../fragments/_configure-redirect-uri.mdx'; + +import GuideTip from './_guide-tip.md'; +import ImplementSignInAndSignOut from './_implement-sign-in-and-sign-out.mdx'; +import InitLogtoClient from './_init-logto-client.md'; +import Installation from './_installation.mdx'; + + + +### Installation \{#installation} + + + +### Init LogtoClient \{#init-logtoclient} + + + +### Configure redirect URI \{#configure-redirect-uri} + + + +### Implement sign-in and sign-out \{#implement-sign-in-and-sign-out} + + + + diff --git a/docs/quick-starts/framework/android/_implement-sign-in.mdx b/docs/quick-starts/framework/android/_implement-sign-in.mdx deleted file mode 100644 index 18d2ece1378..00000000000 --- a/docs/quick-starts/framework/android/_implement-sign-in.mdx +++ /dev/null @@ -1,49 +0,0 @@ -import redirectUriFigure from '../../assets/android-redirect-uri.png'; -import ConfigureRedirectUri from '../../fragments/_configure-redirect-uri.mdx'; - -Before starting, you need to add a redirect URI in the Admin Console for your application. - -In Android, the redirect URI follows the pattern: `$(LOGTO_REDIRECT_SCHEME)://$(YOUR_APP_PACKAGE)/callback`: - -- The `LOGTO_REDIRECT_SCHEME` should be a custom scheme in the reverse domain format. -- The `YOUR_APP_PACKAGE` is your app package name. - -Assuming you treat `io.logto.android` as the custom `LOGTO_REDIRECT_SCHEME`, and `io.logto.sample` is your app package name, the Redirect URI should be `io.logto.android://io.logto.sample/callback`. - - - -After the redirect URI is configured, we add a `signIn` method to your `LogtoViewModel.kt`, which will call `logtoClient.signIn` API to invoke the Logto sign-in page: - -```kotlin -//...with other imports -class LogtoViewModel(application: Application) : AndroidViewModel(application) { - // ...other codes - fun signIn(context: Activity) { - logtoClient.signIn(context, "io.logto.android://io.logto.sample/callback") { logtoException -> - logtoException?.let { println(it) } - } - } -} -``` - -Now setup on-click listener for the sign-in button in your `MainActivity.kt` to call the `signIn` method: - -```kotlin -//...with other imports -class MainActivity : AppCompatActivity() { - override fun onCreate(savedInstanceState: Bundle?) { - //...other codes - - // Assume you have a button with id `sign_in_button` in your layout - val signInButton = findViewById