diff --git a/docs/sdk/pnp/android/custom-authentication.mdx b/docs/sdk/pnp/android/custom-authentication.mdx index a42bc03c3..b55251879 100644 --- a/docs/sdk/pnp/android/custom-authentication.mdx +++ b/docs/sdk/pnp/android/custom-authentication.mdx @@ -9,40 +9,30 @@ import Tabs from "@theme/Tabs"; import GrowthPlanNote from "@site/src/common/docs/_growth_plan_note.mdx"; import SMSPasswordless from "@site/src/common/sdk/pnp/android/_sms_passwordless.mdx"; +## Configuration + To use custom authentication (Using Social providers or Login providers like Auth0, AWS Cognito, -Firebase etc. or even your own custom JWT login) you can add the configuration to the `loginConfig` -parameter of the `Web3AuthOptions` object during the initialization. +Firebase etc. or even your own custom JWT login) you can add the configuration using `loginConfig` +parameter during the initialization. The `loginConfig` parameter is a key value map. The key should be one of the `Web3AuthProvider` in its string form, and the value should be a `LoginConfigItem` instance. -First, configure your own verifier in the Web3Auth Dashboard to use custom authentication. - - +To use custom authentication, first you'll need to configure your own verifier in the Web3Auth +Dashboard in "Custom Authentication" section. +[Learn how to create a custom verifier](/auth-provider-setup/verifiers). :::tip Create Custom Verifier -Check out how to create a **[Custom Verifier](/auth-provider-setup/verifiers)** on the Web3Auth -Dashboard. - -::: - -:::info using dapp share - -- dApp Share is only returned for the Custom verifiers. -- Also, 2FA should be enabled for the account using it. Use `mfaLevel = MFALevel.MANDATORY` in the - `LoginParams` during login. See **[MFA](/sdk/pnp/android/mfa)** for more details. +Learn how to create a [Custom Verifier](/auth-provider-setup/verifiers) on the Web3Auth Dashboard. ::: -Then, you should specify the details of your verifier in the `LoginConfigItem` struct, the details -of this struct are as follows: - -## `LoginConfigItem` + -### Arguments +### Parameters -`LoginConfigItem` +After creating the verifier, you can use the following parameters in the `LoginConfigItem`. - - -### `typeOfLogin` - -```kotlin enum class TypeOfLogin { @SerializedName("google") GOOGLE, @@ -135,6 +117,11 @@ enum class TypeOfLogin { } ``` + + + +### Usage + -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.GOOGLE, - clientId = getString(R.string.google_client_id) // google's client id + clientId = getString(R.string.google_client_id) // Google's client id )) // focus-end ) ) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams(Provider.GOOGLE) +) +// focus-end ``` +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( - context = this, - clientId = getString (R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object - // focus-start - loginConfig = hashMapOf("facebook" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard - typeOfLogin = TypeOfLogin.FACEBOOK, - clientId = getString(R.string.facebook_client_id) // facebook's client id - )) - // focus-end - ) -) -``` +val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // +Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, redirectUrl = +Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("facebook" to +LoginConfigItem( verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = +TypeOfLogin.FACEBOOK, clientId = getString(R.string.facebook_client_id) // Facebook's client id )) +// focus-end ) ) + +// focus-start val loginCompletableFuture: CompletableFuture = web3Auth.login( +LoginParams(Provider.Facebook) ) // focus-end +```` +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.JWT, - clientId = getString (R.string.auth0_project_id) // auth0's client id + clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end ) ) -``` + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams(Provider.JWT) +) +// focus-end +```` +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( - context = this, - clientId = getString (R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object - // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard - typeOfLogin = TypeOfLogin.JWT, - )) - // focus-end - ) -) -``` +val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // +Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, redirectUrl = +Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to +LoginConfigItem( verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = +TypeOfLogin.JWT, )) // focus-end ) ) - +// focus-start val loginCompletableFuture: CompletableFuture = web3Auth.login( +LoginParams(Provider.JWT) ) // focus-end +```` + -## `ExtraLoginOptions` for special login methods +## Configure Extra Login Options Additional to the `LoginConfig` you can pass extra options to the `login` function to configure the login flow for cases requiring additional info for enabling login. The `ExtraLoginOptions` accepts -the following parameters: +the following parameters. + +### Parameters - -## Single Verifier +### Single Verifier Usage -### Using Auth0 Login + + + Auth0 has a special login flow, called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the login function. -```tsx -web3Auth = Web3Auth ( - Web3AuthOptions ( +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard for auth0 configuration + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.JWT, - clientId = getString (R.string.auth0_client_id) // auth0's client id, get it from auth0 dashboard + clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = - web3Auth.login(LoginParams(Provider.JWT, - // focus-start - extraLoginOptions = ExtraLoginOptions( - domain: "https://username.us.auth0.com", // domain of your auth0 app - verifierIdField: "sub", // The field in jwt token which maps to verifier id. - ) - // focus-end - )) +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + // focus-start + extraLoginOptions = ExtraLoginOptions( + domain: "https://username.us.auth0.com", // Domain of your Auth0 app + verifierIdField: "sub", // The field in jwt token which maps to verifier id. + ) + // focus-end + ) +) ``` -### Custom JWT Login + + If you're using any other provider like Firebase/ AWS Cognito or deploying your own Custom JWT server, you need to put the jwt token into the `id_token` field of the `extraLoginOptions`, additionally, you need to pass over the `domain` field as well, which is mandatory. If you don't have a domain, just passover a string in that field. ```kotlin -web3Auth = Web3Auth ( - Web3AuthOptions ( +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard for auth0 configuration + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.JWT, )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = - web3Auth.login(LoginParams(Provider.JWT, - // focus-start - extraLoginOptions = ExtraLoginOptions( - id_token: "Your JWT id token", - ) - // focus-end - )) +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + // focus-start + extraLoginOptions = ExtraLoginOptions( + id_token: "Your JWT id token", + ) + // focus-end + ) +) ``` -### Email Passwordless + -To use the `EMAIL_PASSWORDLESS` login, you need to put the email into the `login_hint` field of the -`extraLoginOptions`. + +To use the Email Passwordless login, you need to put the email into the `login_hint` parameter of +the `ExtraLoginOptions`. By default, the login flow will be `code` flow, if you want to use the +`link` flow, you need to put `flow_type` into the `additionalParams` parameter of the +`ExtraLoginOptions`. ```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + network = Network.MAINNET, + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + ) +) + val loginCompletableFuture: CompletableFuture = web3Auth.login( LoginParams( Provider.EMAIL_PASSWORDLESS, @@ -398,28 +424,33 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ) ``` -### SMS Passwordless + + To use the SMS Passwordless login, send the phone number as the `login_hint` parameter of the `ExtraLoginOptions`. Please make sure the phone number is in the format of +\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). + + -## Aggregate Verifier +### Aggregate Verifier Usage You can use aggregate verifier to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. ```kotlin -web3Auth = Web3Auth ( - Web3AuthOptions ( +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), - network = Network.SAPPHIRE_MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + network = Network.MAINNET, + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf( "google" to LoginConfigItem( @@ -441,20 +472,20 @@ web3Auth = Web3Auth ( ) ) -// Google Login // focus-start +// Google Login web3Auth.login(LoginParams(Provider.GOOGLE)) // focus-end -// Auth0 Login // focus-start +// Auth0 Login web3Auth.login(LoginParams( Provider.JWT, extraLoginOptions = ExtraLoginOptions( domain = "https://web3auth.au.auth0.com", verifierIdField = "email", - isVerifierIdCaseSensitive = false) + isVerifierIdCaseSensitive = false ) -) +)) // focus-end ``` diff --git a/docs/sdk/pnp/android/initialize.mdx b/docs/sdk/pnp/android/initialize.mdx index f9cf64645..cf68f3d69 100644 --- a/docs/sdk/pnp/android/initialize.mdx +++ b/docs/sdk/pnp/android/initialize.mdx @@ -17,21 +17,13 @@ However, Initialization is a two-step process: 1. [Creating a Web3Auth Instance](#create-web3auth-instance) 2. [Setting a Result URL](#set-result-url) +## Create Web3Auth Instance + Please note that these are the most critical steps where you must pass on different parameters according to the preference of your project. Additionally, You must configure Whitelabeling and Custom Authentication within this step if you wish to customize your Web3Auth Instance. -## Create Web3Auth Instance - -In your activity, create a `Web3Auth` instance with your Web3Auth project's configurations. - -```kotlin -web3Auth = Web3Auth(Web3AuthOptions) -``` - -### Arguments - -#### `Web3AuthOptions` +### Parameters The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. @@ -80,112 +72,12 @@ data class Web3AuthOptions( ``` - -### Instance +### Initialize Web3Auth -### Session Management - -The Session Management feature allows you to check the existing sessions with Web3Auth. The -`sessionResponse()` will allow users to remain authenticated with Web3Auth for up to 1 day default, -or a maximum of 7 days, or until they logout or session data is cleared. To change the default -session time, you can pass `sessionTime` in `Web3AuthOptions`. - -```kotlin -// Call sessionResponse() in onCreate() to check for any existing session. -val sessionResponse: CompletableFuture = web3Auth.initialize() -sessionResponse.whenComplete { _, error -> - if (error == null) { - Log.d("MainActivity_Web3Auth", "User already logged in") - // Add your logic - } else { - Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong") - // Ideally, you should initiate the login function here. - } -} -``` - -:::note - -If you're looking for `refreshToken` to maintain the JWT session, use this method instead to extend -the session. - -::: - ## Set Result URL - -## Example - -```kotlin -class MainActivity : AppCompatActivity() { - // ... - private lateinit var web3Auth: Web3Auth - - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - setContentView(R.layout.activity_main) - - web3Auth = Web3Auth( - Web3AuthOptions(context = this, - clientId = getString(R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth") - ) - ) - - // Handle user signing in when app is not alive - web3Auth.setResultUrl(intent?.data) - - // Calls sessionResponse() to check for any existing session. - val sessionResponse: CompletableFuture = web3Auth.initialize() - sessionResponse.whenComplete { _, error -> - if (error == null) { - Log.d("MainActivity_Web3Auth", "User already logged in") - // Add your logic - } else { - Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong") - // Ideally, you should initiate the login function here. - } - } - - // Setup UI and event handlers - val signInButton = findViewById