Secrecy auth

Secrecy auth is the service that gives your application an authenticated Secrecy client. The user signs in through the Secrecy SSO, and your application gets back a ready-to-use SecrecyClient. You never store a password, and you never see the user's master key: the Secrecy sign-in page unlocks the user's identity keys, and only those keys are loaded on the user device at login, so everything that follows can encrypt and decrypt locally.

How Secrecy auth works

The authentication happens on the hosted Secrecy authentication page. The login function sends the user there with a full page redirect, and brings back a session, a JWT and the user key pairs.

Because Secrecy is a Single Sign-On provider, the user authenticates once with a single trusted identity and no new password has to be stored by your application.

Managing authentication

Once the user is logged in, the session is persisted in the browser. A later page load does not need a new login: getSecrecyClient rebuilds the client from the stored credentials. The session can be ended at any time with the logout method, which also wipes the locally stored keys.

Everything in the Secrecy SDK starts with an authenticated client. This page shows how to obtain one, and the options both entry points accept.

Log the user in

The login function opens the Secrecy SSO, persists the returned session and keys, and resolves a ready-to-use client. The page is left before the promise resolves.

import {
  getSecrecyClient,
  login,
  type SecrecyClient,
  setup,
} from '@secrecy/lib';
 
const loginUser = async (): Promise<SecrecyClient | null> => {
  try {
    const client = await login({
      appId: '<YOUR_APP_ID>',
      // optional fields:
      scopes: { email: true },
      path: window.location.pathname,
      backPath: document.referrer,
      redirect: true,
    });
 
    return client;
  } catch (error) {
    console.error(error);
    return null;
  }
};

Reuse the stored client

Once the credentials are stored by a first login, getSecrecyClient gives the client back without asking the user to sign in again. It is synchronous, but the crypto library has to be initialized first with setup.

const getSecrecyClientFromStorage = async (): Promise<SecrecyClient | null> => {
  // Initialize the crypto library before touching the stored key pairs
  await setup();
 
  // Returns null when no session has been stored yet
  return getSecrecyClient();
};

Client options

getSecrecyClient and login both take an options object.

// Retrieve a client already stored by a previous login
getSecrecyClient(opts?: {
  // Read the credentials from sessionStorage instead of localStorage
  session?: boolean;
  // Override the Secrecy urls (auth, account, api, data)
  secrecyUrls?: Partial<SecrecyUrls>;
}): SecrecyClient | null;
 
// Start an authentication flow
login(params: {
  appId?: string;
  // Expected user / organization. A mismatch forces a new login
  context?: { userId?: string; orgId?: string };
  // Full page navigation to the Secrecy authentication page
  redirect?: boolean;
  path?: string | null;
  backPath?: string;
  scopes?: { email: boolean };
  // Store the credentials in sessionStorage instead of localStorage
  session?: boolean;
  secrecyUrls?: Partial<SecrecyUrls>;
  // Ignore any cached client and always start a new login
  forceLogin?: boolean;
}): Promise<SecrecyClient | null>;

When redirect is true, login resolves to null on the first call, because the browser navigates away to the Secrecy authentication page. It resolves with a SecrecyClient once the user comes back.