Skip to main content

Sign In With Your SELF

The SIWYS (Sign In With Your SELF) process enables secure authentication using a challenge-response paradigm, similar to credential requests, but without requesting any credentials. Instead, the user's SELF agent receives a challenge, signs it, and returns the response to prove control over their identity.

note

Ensure that Keymaster is installed, initialized, and started as described in the Keymaster installation documentation before implementing the SIWYS flow.

SIWYS Flow Overview​

  1. Initiate Challenge: The relying party creates a challenge using the Keymaster SDK and provides a callback endpoint for the response.
  2. User Receives Challenge: The user's SELF agent receives the challenge and signs it using their private key.
  3. Submit Response: The signed challenge is sent back to the relying party via the callback endpoint.
  4. Verify Response: The relying party verifies the signature to confirm the user's identity.

Key Differences from Credential Requests​

  • No credentials are requested or exchanged.
  • The process is focused solely on authentication via challenge-response.

Example Sequence​

Refer to the code samples below for implementation details. In this example:

  • The relying party creates a challenge object and sends it to the user's SELF agent.
  • The agent signs the challenge and returns the response.
  • The relying party verifies the response using the Keymaster SDK.

This process ensures that only the legitimate user, who controls the private key, can successfully complete the challenge and continue with their SELF.

Create a SIWYS Challenge​

const challengeData = {
  challenge: {
    callback: "<YOUR_RESPONSE_API_ENDPOINT>",
  },
};

const challenge = await Keymaster.createChallenge(challengeData);
return challenge;

Handle, Decrypt, and Verify Challenge Response​

const verifyResponse = async (responseDID: string, options?: any) => {
    const { retries = 5, delay = 2000 } = options || {};

    const response: ChallengeResponse = await Keymaster.verifyResponse(
        responseDID,
        {
            retries,
            delay,
        }
    );
};

At this point you now have the DID of the user who completed the SIWYS flow and can grant access to the user or perform other actions based on the authenticated identity.