Authentication: SSO Links

Logging users into your application from within Duda.

If your application has it's own UI that users must log in to in order to use features of your platform, you will need to verify users by using Duda's SSO pattern documented here. After verification, you should log the user into your application directly and by-pass any login screens.

📘

Cookies will need the SameSite attribute set to None

By default, most browsers will assume a value of Lax for cookies with an undefined SameSite attribute. That means that the cookie will only be sent along with requests to the origin site.

We recommend only setting the attribute to None on cookies for requests to the base_sso_url.

SSO link format

When users access your UI via an iframe in Duda's editor, Duda will render an iframe to the URL specified in the manifest under base_sso_url with additional parameters.
The SSO link format is as follows, using https://app.domain.com/app/login as base_sso_url:

https://app.domain.com/app/login?site_name={{site name}}&timestamp={{time stamp}}&lang={{use langauge code}}&is_white_label={{false}}&sdk_url={{SDK URL}}&current_user_uuid={{user uuid}}&secure_sig={{signature}}

The SSO link includes two types of parameters:

  • SSO Specific Parameters:
    • Timestamp
    • Site Name
    • SDK URL
    • SSO Signature
  • Additional Parameters:
    • Language
    • Is white-label user (based on d_aware)
    • Current User Account UUID

Duda passes a signature signed by the app-specific private key (which Duda stores). You should verify the SSO signature to validate that the user should be allowed to log in. Use the public key in your app's manifest to verify the signature.

Duda formats our keys using PKCS#1 (default for RSA) with a 2048 bit key length. Duda URL encodes the entire URL string before redirecting the user to that URL, so you should be sure to URL decode each value passed. This is the same as: RFC3986.

You should verify the data by concatenating the site_name, sdk_url, and timestamp with a colon between each. See the following examples:

$sig_data_to_verify = $params['site_name'] . ':' . $params['sdk_url'] . ':'
            . $params['timestamp']
async authenticateAPI(payload: AuthDudaInterface): Promise<boolean> {
  if (
    !payload?.sdkUrl ||
    !payload?.timestamp ||
    !payload?.secureSig ||
    !payload?.siteName
  ) {
    throw new HttpException(
      'Bad User Input: all fields are mandatory',
      HttpStatus.BAD_REQUEST,
    );
  }
  const { sdkUrl, secureSig, siteName, timestamp } = payload;
  const decodedSignature = decodeURIComponent(secureSig);
  const decodedSdkUrl = decodeURIComponent(sdkUrl);
  const decodedSiteName = decodeURIComponent(siteName);
  const sigDataToVerify = `${decodedSiteName}:${decodedSdkUrl}:${timestamp}`;
  return (
    sigDataToVerify ===
    crypto
      .publicDecrypt(
        '-----BEGIN PUBLIC KEY-----\n' +
          process.env.DUDA_PUBLIC_KEY +
          '\n-----END PUBLIC KEY-----',
        Buffer.from(decodedSignature, 'base64'),
      )
      .toString()
  );
}

Additionally, Duda encodes the Signature in Base64 before sending it, so you should decode it as well. Most RSA/Crypto libraries have support for base64 decoding as part of the process.

Time Validity of SSO Links

Apps are expected to refuse SSO links with a timestamp older than 120 seconds before the SSO link HTTP request is received by the App.

🚧

Enforcement

Duda cannot technically enforce such a policy. However, Duda will, from time-to-time, test if Apps in compliance with this policy.

User language

Duda passes the language of the active user in the lang query parameter of the SSO link. App's iframe should localize according to this parameter. Note that for each Duda site there can be several users working on different languages. The list of language codes is given in the following table:

Code

Language

en

English

en_gb

English (UK)

fr

French

de

German

nl

Netherlands

it

Italian

ja

Japanese

pt

Portuguese

pl

Polish

es

Spanish (Spain)

es_ar

Spanish (LATAM)

fi

Finnish

tr

Turkish

ar

Arabic


What’s Next
Did this page help you?