Authentication

Skiff 2 provisions Google Identity-Aware Proxy (IAP) in front of every service by default. You don't need to configure anything to get authentication — by default, only users with an @allenai.org account can reach your app.

To grant access to other domains, specific users, or Google Groups while still requiring login, see Allowing other domains, users, or groups.

For public-facing apps, set allowUnauthenticated: true on the service in skiff2.json:

{
    "services": [
        {
            "name": "web",
            "allowUnauthenticated": true
        }
    ]
}

See the skiff2.json reference for all available options.

For more on how IAP works and how to manage access, see the Google IAP documentation.

Allowing other domains, users, or groups​

By default, only @allenai.org accounts can reach your service. To grant access to additional Google Workspace domains, individual users, or Google Groups, set allowedPrincipals on the service. IAP still forces a Google sign-in — this list controls who passes the check after they've signed in.

{
    "services": [
        {
            "name": "web",
            "allowedPrincipals": [
                "domain:allenai.org",
                "user:contractor@example.com",
                "group:partners@allenai.org"
            ]
        }
    ]
}

allowedPrincipals defaults to ["domain:allenai.org"], so if you set it you'll usually want to keep domain:allenai.org in the list alongside your additions.

Each entry is a literal GCP IAM member identifier:

allowedPrincipals is ignored when allowUnauthenticated: true (the service is fully public in that case). To make a service public, use allowUnauthenticated, not "allUsers" here.

See the skiff2.json reference for the full field spec.

Identifying the user​

When a request reaches your service through IAP, the authenticated user's email is available on the X-Goog-Authenticated-User-Email request header.

The header value is prefixed with an identity namespace (e.g. accounts.google.com:user@allenai.org). You'll typically want to strip everything up to and including the first : to get the bare email address.

Mixing public and private pages​

IAP can't gate some paths and leave others open on the same service, but you can get the same effect at the application layer:

1. Set allowUnauthenticated: true on the service so every request reaches your app.
2. In your handler, verify the X-Goog-IAP-JWT-Assertion header to identify the user (see Verifying the user on mixed services below).
3. If the request is for a private page and the JWT is missing or invalid, redirect the user to the same URL with ?gcp-iap-mode=FORCE_LOGIN appended. IAP intercepts this parameter, walks the user through Google sign-in, and redirects them back to the original URL with a valid JWT attached.

Verifying the user on mixed services​

On a mixed service, the only trustworthy signal of the caller's identity is the X-Goog-IAP-JWT-Assertion header. It's a signed JWT that IAP attaches to any request where the user has already authenticated. Your app verifies it and reads the user's email from the claims.

A valid verification checks four things:

1. Signature — verify the JWT against IAP's public keys, published at Google's IAP public key endpoint. Google's official client libraries fetch and cache these for you.
2. Issuer — must be https://cloud.google.com/iap.
3. Audience — must match your service exactly, in the form /projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME. Find PROJECT_NUMBER in the GCP console for your project.
4. Email claim — after the JWT is verified, read the email claim and apply whatever access rules your app needs (e.g. require an @allenai.org suffix).

If any step fails, treat the request as unauthenticated.

For development, it's common to bypass verification behind an environment variable (e.g. LOCAL_DEVELOPMENT) and return a stub email, since IAP isn't in front of your local server.

Google's Getting the user's identity with IAP docs have sample code in several languages and the full list of claims available on the JWT.

How force-login works​

When your service has allowUnauthenticated: true, IAP won't challenge visitors on its own. To trigger a sign-in from your app, redirect the user to their current URL with the gcp-iap-mode=FORCE_LOGIN query parameter:

https://my-app.pandajungle.org/admin?gcp-iap-mode=FORCE_LOGIN

IAP intercepts requests containing this parameter, enforces authentication, and then redirects the user back to the URL without the parameter. On that subsequent request, the X-Goog-Authenticated-User-Email header will be present.

This keeps the auth decision in your code — useful when "is this page public?" depends on the route, a feature flag, or the resource being requested.

See Google's IAP as an authentication proxy docs for more details.

Need something more complicated? Use Auth0​

IAP covers the common case (gate the app to @allenai.org, or make it fully public). If you need anything beyond that — external users, per-user roles, organizations, SSO into a non-Google IdP, machine-to-machine tokens, etc. — AI2 runs an Auth0 tenant you can use instead.

Ask in #auth0-users on Slack to get onboarded. You'll typically run your service with allowUnauthenticated: true and let Auth0 handle auth inside your app.