Skip to main content

Authenticate using JWT

If you cannot - or don't want to - integrate OIDC, you CAN use a JWT based sign-in method.

tip

OIDC might be too much for your application. You SHOULD use JWT instead if:

  • You don't have multiple other apps of your own that you need login for
  • You don't have any other third party apps besides Star Accounts

To sign in with JWT, provide us with the following information:

  • Authorization URL
  • JWKS URL

The flow SHOULD work like this:

  1. User attempts authentication at Star Accounts (https://login.starcommunity.app/auth/login)
  2. User selects your association as login provider
  3. User gets redirected to Authentication URL (https://<yoursite>/token/star_community?nonce=<nonce>)
  4. User authenticates on your website (https://<yoursite>/login)
  5. (optional) User approves sign-in to Star Accounts on your website (https://<yoursite>/approve)
  6. Redirect back to Star Accounts using the Redirect URL (https://login.starcommunity.app/auth/callback/association1/#token=<JWT>)

URLs​

Authentication URL​

The Authentication URL is the URL that we will send the user to upon login. You MAY use any URL pattern here, but we recommend following a pattern with the app name in the title, such as https://<your site>/token/<app-name>.

You MUST register the redirect URI with the app name beforehand. We will give you two redirect URLs, one for production and one for testing.

You MUST at least be able to register two apps (hubble & hubble-test).

Star Accounts will always add a nonce query parameter to this URL. The nonce MUST be present in the return token if it's sent. This allows the frontend to check if the request was sent by us and to prevent Replay Attacks.

JWKS URL​

You SHOULD also provide a JWKS URL (RFC 7517), such that we can obtain the public keys for verification. Only RSA signature keys need to be listed. You MAY list multiple keys, identified by the kty parameter in the JWK and the kty header in the JWT.

Redirect URL​

We will provide you with two Redirect URLs, one for production & one for test. You MUST redirect to this URL with the token in a URL fragment.

For example: https://login.starcommunity.app/auth/callback/association1/#token=<JWT>

warning

We do not support returns in query parameters as those URLs might get logged or cached in the user browser.

JWT contents​

Your JWT MUST have the following claims (or equivalents):

  • sub: Identifier that we can store to identify this user in the future.
    • You may use your internal identifiers, a hashed version or an anonymised ID.
    • Identifier must not change for the same user over time.
  • iat: Issued at timestamp
  • exp: Expiry timestamp
  • name: Full name of the user.
  • given_name: Given name(s) or first name(s) of the user, we will use this to address them.
  • email: E-mail address of the user, used for linking accounts.
  • email_verified: Boolean indicating if the e-mail address was verified, such as by verification email or payment link.
  • is_member: Boolean indicating if this is an active member of your association.
  • nonce: Nonce from the query parameter received on the original request.

JWT Expiration​

You SHOULD issue tokens with a short duration, we recommend 5 minutes. You should set issued at to your current server time.

JWT Signing​

Signing with RSA public/private keys​

You SHOULD sign your JWTs with an RSA method, such as RS256, RS384 or RS512. You MUST provide the corresponding public keys on the JWKS endpoint. You MAY use different keys with a key identifier and kty header on the JWT.

Signing with shared secrets​

If you don't want others to be able to verify the JWT, you CAN consider provide us with a shared secret and using the HS512 signing method. This method SHOULD be avoided for new implementations, as it is more likely to suffer from accidental key exposure (especially with multiple apps) and lead to fake tokens.