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
- Scroll to the Embedded App Sign-in section.
- Under Registered Embedded Apps, click Add an embedded app.
- In Origin, enter the app’s origin, such as
https://forms.example.com. - Optionally, enter a Name to help you recognize the app later.
- Click Save.
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 addsiw_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_tokenparameter. - 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 theCurator.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 freshiw_tokenadded, replacing anyiw_tokenalready 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 asforms.example.comorforms.example.com:8443, or a full URL, whose scheme must then match the registered origin. When Curator refuses, it fails with an object that hasstatus,code, andmessageproperties.
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:
audienceis required. It is the app’s host, with the port only when the app uses a non-standard one.schemeis optional,httporhttps. When it is given, the registered origin must use that scheme.
https://<host>/<basepath>/user/embedauth/token.
Every response is JSON:
-
200: the token was issued.
expires_atis the token’s expiry in Unix seconds, andexpires_inis 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"}:audienceis missing or is not a registered app, under the givenschemewhen one is given. -
429
{"error": "rate_limited"}: the user asked for more than 30 tokens in one minute. TheRetry-Afterheader says how many seconds to wait. -
500
{"error": "signing_failed"}: Curator could not sign the token. The reason is written to the Curator log.
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.