Sismo Docs
  • Welcome to Sismo
    • What is Sismo?
  • Build with Sismo Connect
    • Overview
    • Installation
    • Sismo Connect Cheatsheet
    • Tutorials
      • Get Your appId - Create a Sismo Connect App
      • Onchain Tutorial (1/2): Code Your Airdrop Contract With Privately-Aggregated Data
      • Onchain Tutorial (2/2): Deploy Your Airdrop Contract
    • Technical Documentation
      • Sismo Connect Configuration
      • Auths
      • Claims
      • Signature
      • Packages
        • Sismo Connect Client: Request
        • Sismo Connect React: Request
        • Sismo Connect Server: Verify Offchain
        • Sismo Connect Solidity Library: Verify Onchain
    • FAQ
  • Data Groups
    • Overview
    • Tutorials
      • Factory Guide: Create a Data Group in 5 Minutes
      • Sismo Hub Guide: Create Data Groups Programmatically
      • Sismo Hub Guide: Add a Data Provider to the Sismo Factory
    • Sismo Hub
      • Sismo Hub Repository
        • Group Generators
        • Data Providers
        • Data Operators
        • Command Line Interface
      • Accounts Registry Tree
  • Data Vault
    • Overview
    • Vault Identifiers
    • Proving Schemes
      • Hydra-S1
      • Hydra-S2
    • Commitment Mapper
  • Resources
    • Deployed Contract Addresses
    • Sismo API
      • API Links
      • Query From a Client
      • Group
        • Get groups
        • Get group snapshots
      • Common Parameters
      • Advanced Filtering
      • Transaction
  • Links
    • Sismo Landing Page
    • Sismo Factory
    • Sismo App Store
    • Sismo Builder Resources
    • GitHub
    • Discord
    • Twitter
    • Blog
Powered by GitBook
On this page
  • Type definitions
  • Integrations
  • Making an AuthRequest - Front-end integration
  • Verifying an AuthRequest
  1. Build with Sismo Connect
  2. Technical Documentation

Auths

PreviousSismo Connect ConfigurationNextClaims

Last updated 1 year ago

Sismo Connect can be used to authenticate a user from multiple sources, either from web2 or web3.

Type definitions

The AuthRequest is an object with the following properties:

  • AuthType (required): defines the type of authentication required. The following authType are currently supported:

    • VAULT: Sismo Connect returns the user's vaultId for the application that requested it. It is a deterministic anonymous identifier (hash(userVaultSecret, AppId, ..)) See more information about Vault Identifiers .

    • GITHUB: Sismo Connect returns the user's GitHub account id.

    • TWITTER Sismo Connect returns the user's Twitter account id.

    • EVM_ACCOUNT: Sismo Connect returns the user's Ethereum address.

    • TELEGRAM : Sismo Connect returns the user's Telegram account id.

  • userId (optional): requests the user to have a predefined account.

  • isOptional(optional): by default set to false. Allows the user to optionally authenticate with this AuthType.

// Types (typescript version)
enum AuthType {
    VAULT = 0,
    GITHUB = 1,
    TWITTER = 2,
    EVM_ACCOUNT = 3,
    TELEGRAM = 4,
}

type AuthRequest = {
    authType: AuthType;
    userId?: string;
    isOptional?: boolean;
};

Integrations

Making an AuthRequest - Front-end integration

Making an AuthRequest is only possible in the front end as the request redirects users to the Sismo Data Vault app, where users can generate a zero-knowledge proof.

  • AuthRequests are passed as props of the SismoConnectButton either through:

    1. the auth props for one authentication request: AuthRequest or,

    2. the auths props for several authentication requests: AuthRequest[]

  • Responses are received through either:

    1. the onResponse: (response: SismoConnectResponse) => void callback for offchain verification or,

    2. the onResponseBytes (response: string) => void callback for onchain verification.

One AuthRequest - code example

app.tsx
import { SismoConnectButton, AuthType, SismoConnectClientConfig, SismoConnectResponse } from "@sismo-core/sismo-connect-react";

<SismoConnectButton 
    // the client config created
    config={config}
    // request a proof of account ownership 
    // (here Vault ownership)
    auth={{authType: AuthType.VAULT}}
    onResponse={async (response: SismoConnectResponse) => {
	//Send the response to your server to verify it
	//thanks to the @sismo-core/sismo-connect-server package
    }}
    onResponseBytes={async (bytes: string) => {
        //Send the response to your contract to verify it
        //thanks to the @sismo-core/sismo-connect-solidity package
    }}
/>

Multiple AuthRequests - code example

app.tsx
// You can also create several auth requests 
// in the same button
import { SismoConnectButton, AuthType, SismoConnectClientConfig, SismoConnectResponse } from "@sismo-core/sismo-connect-react";

<SismoConnectButton 
    config={config}
    // request multiple proofs of account ownership 
    // (here Vault ownership and Twitter account ownership)
    auths={[
        {authType: AuthType.VAULT},
        {authType: AuthType.TWITTER},
    ]}
    onResponse={async (response: SismoConnectResponse) => {
	//Send the response to your server to verify it
	//thanks to the @sismo-core/sismo-connect-server package
    }}
    onResponseBytes={async (bytes: string) => {
        //Send the response to your contract to verify it
        //thanks to the @sismo-core/sismo-connect-solidity package
    }}
/>
  • One or multiple AuthRequests can be made using the sismoConnect.request() method available on the sismoConnect variable.

  • The response could be received through either:

    1. the sismoConnect.getResponse() method for offchain verification or,

    2. the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

App.tsx
import { useSismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-react";

const { sismoConnect } = useSismoConnect({ config });

// Making the request a proof of account ownership 
// (here Vault ownership)
function onClick(){
  sismoConnect.request({
      auth: {authType: AuthType.VAULT}
    });
}

// Proofs are available in two differents types depending on usage (offchain or onchaon verification)
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

Multiple AuthRequests - code example

App.tsx
import { useSismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-react";

const { sismoConnect } = useSismoConnect({ config });

// Making the request for multiple proofs of account ownership 
// (here Vault ownership and Twitter account ownership)
function onClick(){
  sismoConnect.request({
      auths: [
      {authType: AuthType.VAULT},
      {authType: AuthType.TWITTER},
      ]   
    });
}

// Proofs are available in two differents types depending on usage (offchain or onchaon verification)
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}
  • One or multiple AuthRequests can be made using the sismoConnect.request() method available on a SismoConnect instance.

  • The response could be received through either:

    1. the sismoConnect.getResponse() method for offchain verification or,

    2. the sismoConnect.getResponseBytes() method for onchain verification.

One AuthRequest - code example

app.ts
import { SismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-client";

const sismoConnect = SismoConnect({config});

// Making the request a proof of account ownership 
// (here Vault ownership)
function onClick(){
  sismoConnect.request({
      auth: {authType: AuthType.VAULT}
    });
}

// Receive the proofs in two different formats
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

Multiple AuthRequests - code example

app.ts
import { SismoConnect, SismoConnectResponse, AuthType } from "@sismo-core/sismo-connect-client";

const sismoConnect = SismoConnect({config});

// Making the request for multiple proofs of account ownership 
// (here Vault ownership and Twitter account ownership)
function onClick(){
  sismoConnect.request({
      auths: [
      {authType: AuthType.VAULT},
      {authType: AuthType.TWITTER},
      ]   
    });
}

// Receive the proofs in two different formats
const response: SismoConnectResponse | null = sismoConnect.getResponse();
const responseBytes: string | null  = sismoConnect.getResponseBytes();

if(response || responseBytes) {
// Send response to the backend to verify it or,
// Send responseBytes to smart contract to verify it. 
}

Verifying an AuthRequest

Once a user has generated a ZKP on the Data Vault app, your application must verify it. This can be achieved in onchain smart contracts or offchain back ends.

One or multiple AuthRequests can be verified offchain on a backend server using the sismoConnect.verify() method available on a SismoConnect instance.

  • If the proof is valid sismoConnect.verify() returns a result of type SismoConnectVerifiedResult else it will throw an error,

  • the result.getUserId() can be called as shown below to get the userId of the corresponding type.

One AuthRequest - code example

import { SismoConnect, SismoConnectVerifiedResult, AuthType } from "@sismo-core/sismo-connect-server";

const sismoConnect = SismoConnect({config});

async function verifyResponse(sismoConnectResponse: SismoConnectResponse) {
  // verifies the proofs contained in the sismoConnectResponse
  // with respect to the different auths
  // i.e. user prove they own a Vault
  const result: SismoConnectVerifiedResult = await sismoConnect.verify(
    sismoConnectResponse,
    {
      // proofs in the sismoConnectResponse should be valid
      // with respect to a Vault ownership
      auth: { authType: AuthType.VAULT },
    }
  )

  // vaultId = hash(userVaultSecret, appId).
  // the vaultId is an app-specific, anonymous identifier of a vault
  const vaultId = result.getUserId(AuthType.VAULT)
}
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ["@sismo-core/sismo-connect-server"],
  },
}

module.exports = nextConfig

Multiple AuthRequests - code example

import { SismoConnect, SismoConnectVerifiedResult, AuthType } from "@sismo-core/sismo-connect-server";

const sismoConnect = SismoConnect({config});

async function verifyResponse(sismoConnectResponse: SismoConnectResponse) {
  // verifies the proofs contained in the sismoConnectResponse
  // with respect to the different auths
  // i.e. user prove they own a Vault, a Twitter account
  const result: SismoConnectVerifiedResult = await sismoConnect.verify(
    sismoConnectResponse,
    {
      // proofs in the sismoConnectResponse should be valid
      // with respect to a Vault and Twitter account ownership
      auths: [
        { authType: AuthType.VAULT }, 
        { authType: AuthType.TWITTER }
      ],
    }
  )

  // vaultId = hash(userVaultSecret, appId).
  // the vaultId is an app-specific, anonymous identifier of a vault
  const vaultId = result.getUserId(AuthType.VAULT)
  // you can also get the twitterId of the user
  const twitterId = result.getUserId(AuthType.TWITTER)
}

The Sismo Connect Library exposes:

  • a verify() function, which allows you to verify a proof generated by the Sismo Vault app with respect to some requests directly in your contract. The verify() function takes an object containing:

    1. a responseBytes send from the front end,

    2. an auth or auths corresponding to the authentification request made in the front end.

  • a buildAuth() helper to recreate the AuthRequest made in the front-end

  • a SismoConnectHelper.getUserId() helper to retrieve the userId of the corresponding type once the proof has been verified.

One AuthRequest - code example

contract MyContract is SismoConnect { // inherits from Sismo Connect library
 
// call SismoConnect constructor with your appId
constructor(bytes16 appId) SismoConnect(buildConfig(appId)) {}

    function doSomethingUsingSismoConnect(bytes memory sismoConnectResponse) public {    
        SismoConnectVerifiedResult memory result = verify({
            responseBytes: sismoConnectResponse,
            // we want users to prove that they own a Sismo Vault
            // we are recreating the auth request made in the frontend to be sure that 
            // the proof provided in the response is valid with respect to this auth request
            auth: buildAuth({authType: AuthType.VAULT}),       
        });
    
        // if the proofs is valid, we can take the userId from the verified result
        // in this case the userId is the vaultId (since we used AuthType.VAULT in the auth request) 
        // it is the anonymous identifier of a user's vault for a specific app 
        // --> vaultId = hash(userVaultSecret, appId)
        uint256 vaultId = SismoConnectHelper.getUserId(result, AuthType.VAULT);
        
        // do something with this vaultId for example
    }
}

Multiple AuthRequests - code example

contract MyContract is SismoConnect { // inherits from Sismo Connect library
 
// call SismoConnect constructor with your appId
constructor(bytes16 appId) SismoConnect(buildConfig(appId)) {}

    function doSomethingUsingSismoConnect(bytes memory sismoConnectResponse) public {    
        // we want users to prove that they own a Sismo Vault and a Twitter Id
        // we are recreating the auth request made in the frontend to be sure that 
        // the proof provided in the response is valid with respect to this auth request
        
        AuthRequest[] memory auths = new AuthRequest[](2);
        auths[0] = buildAuth({authType: AuthType.VAULT})
        auths[1] = buildAuth({authType: AuthType.TWITTER})
        
        SismoConnectVerifiedResult memory result = verify({
            responseBytes: sismoConnectResponse,
            auths: auths,       
        });
        
        // --> vaultId = hash(userVaultSecret, appId)
        uint256 vaultId = SismoConnectHelper.getUserId(result, AuthType.VAULT);
        uint256 twitterId = SismoConnectHelper.getUserId(result, AuthType.TWITTER);     
        
        // do something with this vaultId and the twitterID
    }
}

Authentication requests are made in the front end using either the or the . Requests are then verified either in a back end using the or in a smart contract using the .

The SismoConnectButton React component is available from the . It is a wrapper of the .

The useSismoConnect hook is available from the . It is a wrapper of the . The useSismoConnect hook exposes the sismoConnect variable.

The exposes a SismoConnect variable.

The exposes a SismoConnect variable.

If you are using Nextjs, you will need to add this config in the next.config.js file to be able to verify the proof. You can find more information .

The exposes a Sismo Connect Library, which can be inherited by your contract either using Foundry or Hardhat.

here
sismo-connect-react package
sismo-connect-client package
sismo-connect-server package
sismo-connect-solidity package
sismo-connect-react package
sismo-connect-client package
sismo-connect-react package
sismo-connect-client package
sismo-connect-client package
sismo-connect-server package
here
sismo-connect-solidity package