Skip to main content
An embedded app can verify which Curator user is viewing it by checking a signed identity token named iw_token. The [IW_TOKEN] placeholder adds that token to one iFrame URL at a time. When you register an app’s origin instead, Curator signs every iFrame element that points at the app without a placeholder, and scripts in Embed Code (HTML) elements can ask Curator for a token for the app. The token is the same one [IW_TOKEN] produces, and the embedded app verifies it the same way. The one difference is the aud claim: automatic signing writes the host in lower case and without the default port (:443 or :80), while [IW_TOKEN] uses the host exactly as it is written in the element URL. See Passing a verified identity with [IW_TOKEN] for the token’s claims and how to check it against Curator’s public keys. Only register apps you or your team control, and that verify Curator’s token. Curator issues tokens for a registered app to every signed-in user who views a page that embeds it.

Registering an App

  1. Scroll to the Embedded App Sign-in section.
  2. Under Registered Embedded Apps, click Add an embedded app.
  3. In Origin, enter the app’s origin, such as https://forms.example.com.
  4. Optionally, enter a Name to help you recognize the app later.
  5. Click Save.
Only a superuser can change the list of registered embedded apps. Other backend administrators see it locked.

Origin Format

An origin is the scheme, the host, and an optional port, and nothing else: Curator saves each origin in lower case. If any origin is not in this format, the save is refused and Curator shows which origin it could not accept. An origin matches a URL only when the scheme, host, and port are all the same. Registering https://forms.example.com does not cover http://forms.example.com, https://forms.example.com:8443, or https://www.forms.example.com. Register each one you embed.

Signing iFrame Elements Automatically

When a signed-in user views a page, Curator adds iw_token=<token> to the URL of every iFrame element that points at a registered origin. For example, https://forms.example.com/form?school=12 loads as https://forms.example.com/form?school=12&iw_token=<token>. A fragment such as #section-2 stays at the end of the URL. Curator leaves the URL as it is when:
  • The element URL contains the [IW_TOKEN] placeholder. The placeholder adds the token instead.
  • The URL already has an iw_token parameter.
  • Nobody is signed in. Anonymous visitors load the plain URL.
  • The URL points at an origin that is not registered.

Signing URLs from an Embed Code (HTML) Element

Placeholders and automatic signing apply only to iFrame elements. When a script in an Embed Code (HTML) element builds an iframe URL in the browser, it can sign that URL with the Curator.embedAuth helper. Curator adds the helper to every page once at least one app is registered, so a script in the element can use it right away. When no app is registered, Curator does not add the helper, so check that it exists first, as the example does.
  • Curator.embedAuth.signUrl(url) returns the URL with a fresh iw_token added, replacing any iw_token already in it. When the URL cannot be signed, because its origin is not registered, nobody is signed in, or Curator refuses the request, it returns the URL unchanged and logs a warning in the browser console. It never fails, so the frame still loads and the embedded app can show its own sign-in message.
  • Curator.embedAuth.getToken(host) returns just the token, for a script that passes it some other way. Pass the app’s host, such as forms.example.com or forms.example.com:8443, or a full URL, whose scheme must then match the registered origin. When Curator refuses, it fails with an object that has status, code, and message properties.
A token expires about a minute after it is issued. Curator does not stop a token from being used twice within that minute: to accept each token only once, the embedded app has to remember the token’s jti claim until it expires. Sign each URL right before you load it, and sign it again for each frame and each reload.

The Token Endpoint

Curator.embedAuth gets its tokens from this endpoint. Scripts on your Curator pages can also call it directly:
  • audience is required. It is the app’s host, with the port only when the app uses a non-standard one.
  • scheme is optional, http or https. When it is given, the registered origin must use that scheme.
The endpoint uses the visitor’s Curator session to decide who the token is for, so it only answers requests from pages on your Curator portal. It does not allow requests from other websites. If Curator is hosted under a base path, include it, such as https://<host>/<basepath>/user/embedauth/token. Every response is JSON:
  • 200: the token was issued.
    expires_at is the token’s expiry in Unix seconds, and expires_in is the number of seconds left until then.
  • 401 {"error": "not_signed_in"}: nobody is signed in, or the user has not finished multi-factor authentication.
  • 403 {"error": "cross_site_request"}: the browser reported that the request came from another website.
  • 404 {"error": "unregistered_audience"}: audience is missing or is not a registered app, under the given scheme when one is given.
  • 429 {"error": "rate_limited"}: the user asked for more than 30 tokens in one minute. The Retry-After header says how many seconds to wait.
  • 500 {"error": "signing_failed"}: Curator could not sign the token. The reason is written to the Curator log.
The token’s aud claim is the audience value, the app’s host or host:port in lower case. The embedded app should confirm that aud matches its own host before it trusts the token.