Skip to main content

Using Custom Authentication in PnP iOS SDK

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 W3AInitParams object 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 W3ALoginConfig struct.

To use custom authentication, first you'll need to configure your own verifier in the Web3Auth Dashboard in Custom Authentication section.

note

This is a paid feature and the minimum pricing plan to use this SDK in a production environment is the Growth Plan. You can use this feature in the development environment for free.

Create Custom Verifier

Check out how to create a Custom Verifier on the Web3Auth Dashboard.

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 W3ALoginParams during login. See MFA for more details.

Once the custom verifier is created, you need to specify the details of your verifier in the W3ALoginConfig struct, the parameters of the struct are as follows:

W3ALoginConfig​

Arguments​

W3ALoginConfig

ParameterDescription
verifierThe name of the verifier that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts String as a value.
typeOfLoginType of login of this verifier, this value will affect the login flow that is adapted. For example, if you choose google, a Google sign-in flow will be used. If you choose jwt, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts TypeOfLogin as a value.
clientIdClient id provided by your login provider used for custom verifier. e.g. Google's Client ID or Web3Auth's client Id if using 'jwt' as TypeOfLogin. It's a mandatory field, and accepts String as a value.
name?Display name for the verifier. If null, the default name is used. It accepts String as a value.
description?Description for the button. If provided, it renders as a full length button. else, icon button. It accepts String as a value.
verifierSubIdentifier?The field in JWT token which maps to verifier id. Please make sure you selected correct JWT verifier id in the developer dashboard. It accepts String as a value.
logoHover?Logo to be shown on mouse hover. It accepts String as a value.
logoLight?Light logo for dark background. It accepts String as a value.
logoDark?Dark logo for light background. It accepts String as a value.
mainOption?Show login button on the main list. It accepts Bool as a value. Default value is false.
showOnModal?Whether to show the login button on modal or not. Default value is true.
showOnDesktop?Whether to show the login button on desktop. Default value is true.
showOnMobile?Whether to show the login button on mobile. Default value is true.

typeOfLogin​

public enum TypeOfLogin: String, Codable {
    case google
    case facebook
    case reddit
    case discord
    case twitch
    case apple
    case github
    case linkedin
    case twitter
    case weibo
    case line
    case email_password
    case passwordless
    case jwt
}
Usage
web3Auth = await Web3Auth(
  W3AInitParams(
    clientId: "YOUR_CLIENT_ID",
    network: .sapphire_mainnet,
    loginConfig: [
      Web3AuthProvider.JWT.rawValue: .init(
        verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard
        typeOfLogin: TypeOfLogin.google,
        clientId: "YOUR_GOOGLE_CLIENT_ID",
      )
    ]
))

ExtraLoginOptions for special login methods​

Additional to the W3ALoginConfig 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:

ParameterDescription
additionalParams?Additional params in [String:String] format for OAuth login, use id_token(JWT) to authenticate with web3auth.
domain?Your custom authentication domain in String format. For example, if you are using Auth0, it can be example.au.auth0.com.
client_id?Client id in String format, provided by your login provider used for custom verifier.
leeway?The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It takes Int as a value.
verifierIdField?The field in JWT token which maps to verifier id. Please make sure you selected correct JWT verifier id in the developer dashboard. It takes String as a value.
isVerifierIdCaseSensitive?Bool to confirm Whether the verifier id field is case sensitive or not.
display?Allows developers the configure the display of UI. It takes String as a value.
prompt?Prompt shown to the user during authentication process. It takes String as a value.
max_age?Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It takes String as a value.
ui_locales?The space separated list of language tags, ordered by preference. For instance fr-CA fr en.
id_token_hint?It denotes the previously issued ID token. It takes String as a value.
id_token?JWT (ID Token) to be passed for login.
login_hint?It is used to send the user's email address during Email Passwordless login. It takes String as a value.
acr_values?acc_values
scope?The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It takes String as a value.
audience?The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes String as a value.
connection?The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It takes String as a value.
state?state
response_type?Defines which grant to execute for the authorization server. It takes String as a value.
nonce?nonce
redirect_uri?It can be used to specify the default url, where your custom jwt verifier can redirect your browser to with the result. If you are using Auth0, it must be whitelisted in the Allowed Callback URLs in your Auth0's application.

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.

web3Auth = await Web3Auth(
  W3AInitParams(
    clientId:"YOUR_CLIENT_ID",
    network: .sapphire_mainnet,
    // Optional loginConfig object
    loginConfig: [
      Web3AuthProvider.JWT.rawValue: .init(
        verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard for auth0 configuration
        typeOfLogin: TypeOfLogin.jwt,
        clientId: "YOUR_AUTH0_CLIENT_ID", // auth0's client id, get it from auth0 dashboard
      )
    ]
  )
)

let result  = await web3Auth.login(W3ALoginParams(selectedLoginProvider,
    extraLoginOptions: .init(
      // Domain of your auth0 app
      domain:"https://username.us.auth0.com",
      // The field in jwt token which maps to verifier id
      verifierIdField: "sub",
    )
))

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.


web3Auth = await Web3Auth(
  W3AInitParams(
    clientId:"YOUR_CLIENT_ID",
    network: .testnet,
    // Optional loginConfig object
    loginConfig: [
      Web3AuthProvider.JWT.rawValue: .init(
        verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard
        typeOfLogin: TypeOfLogin.jwt,
        clientId: "BPi5PB_UiIZ-cPz1GtV5i1I2iOSOHuimiXBI0e-Oe_u6X3oVAbCiAZOTEBtTXw4tsluTITPqA8zMsfxIKMjiqNQ", // get it from web3auth dashboard
      )
    ]
  )
)

let result = await web3Auth.login(
  W3ALoginParams(
    selectedLoginProvider,
    extraLoginOptions: .init(domain:"your-domain", id_token: "your_jwt_token")
  )
)

Email Passwordless​

  • To use the EMAIL_PASSWORDLESS login, you need to put the email into the login_hint field of the extraLoginOptions.
let result = await Web3Auth().login(W3ALoginParams(selectedLoginProvider,
  extraLoginOptions: .init(loginHint: "hello@web3auth.io")
))