Skip to main content

Using SphereGate in your app

Your app doesn't need any code to be protected. If you want to know who signed in, read the headers SphereGate adds to every request it lets through.

Who signed in​

HeaderContains
X-SphereGate-EmailThe visitor's verified email address. Not sent for password visitors.
X-SphereGate-UserAn ID for the visitor that stays the same on this service. Use it as a user key.

SphereGate removes the X-SphereGate- headers it sets from what a visitor sends, then adds its own.

Requests from other services in the same environment over the private network don't pass through SphereGate. If your app also takes private traffic, don't use these headers to decide who someone is on those requests.

Verify the token​

If your app acts on who signed in, verify the signed token in X-SphereGate-Token. Don't trust identity headers alone.

SphereGate sends the visitor's ID token in the X-SphereGate-Token header. It's a JWT signed with ES256. Check it with any JWT library. The values to check are on your service's Access protection card, under For your app: Issuer, Audience and Policy ID.

  1. Check the signature against SphereGate's signing keys at https://spheregate.computesphere.com/.well-known/jwks.json. They're also listed in https://spheregate.computesphere.com/.well-known/openid-configuration. Most JWT libraries take either address directly.
  2. Check iss is https://spheregate.computesphere.com and exp hasn't passed.
  3. Check aud is the Audience shown under For your app.
  4. Check sg_pol is your service's Policy ID. Other services in the same environment get tokens with the same audience, so this check is what ties a token to your service.

The key list can hold more than one key. Pick the key by the token's kid, and if the kid is unknown, fetch the list again, at most once a minute. Don't pin a single key. Most JWT libraries do this for you.

No X-SphereGate-Token header means the request didn't come from a signed-in visitor, for example a request to an always-public path. Treat it as not signed in.

Send visitors to /.well-known/spheregate/logout on your service's address to sign them out:

<a href="/.well-known/spheregate/logout">Sign out</a>

Single-page apps​

A sign-in lasts an hour. After it ends, a background request from your page (fetch or XHR) is sent to sign-in instead of your service, and the browser reports it as a network error. When a request to your own service fails that way, reload the page. Within 24 hours of signing in, a visitor who's still allowed is back in your app without signing in again.