Skip to main content

Sign in with your Star Account

If you want to use a Star Account to sign in to your app or if you want to access the Star Community API with your app, you will need to implement 'Sign in with your Star Account'.

Sign in with your Star Account is implemented with the OpenID Connect protocol.

OpenID Connect​

OpenID Connect (OIDC) is a widely used authentication and authorization protocol for web and mobile applications. Its primary purpose is to enable users to log in to online services or applications using their existing accounts from trusted identity providers (e.g., Google, Facebook or our Hubble Guest Accounts) without the need to create new usernames and passwords.

In essence, OIDC simplifies user authentication by providing a standardized way for applications to verify user identities and obtain basic profile information. It builds on the OAuth 2.0 framework and adds an identity layer on top, making it suitable for single sign-on (SSO) and secure user data sharing between applications.

tip

Do not attempt to implement OpenID Connect yourself, use a library!
You can find libraries for Node.js, PHP and Python at the bottom of this page.

Types of Clients​

In OIDC, we distinguish two types of clients:

  • Confidential Clients: Clients that are running on a server, outside of user control. They can keep secrets.
    Examples: Python/PHP/NodeJS app

  • Public Clients: Clients such as mobile apps or frontends of which all code is in the user's control. We don't trust these.
    Examples: React/Vue app, Android/iOS app

Confidential clients are issued a client secret upon their registration. Keep this key safe! If it is ever leaked, we need to reset it. You cannot send this to your frontend.

Types of API Access​

For the Star Community API, we use OIDC as the framework for logins for all apps using Star Accounts, as well as to authorize scopes to use on behalf of your user. There are two types of possible API endpoint:

  • User API Access: you access the API on behalf of a user. The user gives explicit consent for your app to use their data.
  • App API Access: you access the API on behalf of your app. You will not get personal data for users, but only aggregated data.

User API Access​

Available for both Public and Confidential Clients

To use User API Access, your app needs to use the Star Account sign-in. After sign-in, the user will be requested to approve the data you would like to access. If the user denies sharing data with your app, the login will fail.

For this integration, you will receive a Client ID and register a Redirect URI to return to after login is done.

To give an example, the total data for your client might be:

Client ID: ABCDEF
Redirect URI: http://localhost:3000/callback

We require the use of the Authorization Code Grant with PKCE for User API Access.

App API Access​

Available for only Confidential Clients

Alternatively, you might have access to some data because your app needs aggregated data. For example, you might want to view the total amount of Eendjes sold, or request a list of total sales per customer ID. App API Access is granted by the Hubble Board, upon which your client is registered.

You will receive a Client ID and a Client Secret to use to obtain tokens with the Client Credentials Grant. The Client Secret must remain secret and may only be used in the server of a Confidential Client. You cannot include it directly within your source code (use environment vars instead).

To give an example, the total data for your client might be:

Client ID: ABCDEF
Client Secret: ZXYW

Both User and API API Access​

You may also implement both versions in the same app, provided it is a backend app (or uses an API service). Then, you will both register Redirect URIs for the frontend login (Auth Code with PKCE), as well as obtain a Client Secret for backend use.

Scopes​

To request access to different parts of the API, you will need to use one or multiple scopes. You can find detailed information here: Scopes. We will use example_scope in the examples below.

Implementing OpenID Connect​

Prefer using the issuer variable, which you can set to https://login.starcommunity.app. If you need to use the discovery variable, input https://login.starcommunity.app/.well-known/openid-configuration instead.

tip

On test, use login.test.starcommunity.app instead.

We only support the Authorization Code Grant with PKCE or the Client Credentials Grant.

Javascript (frontend)​

We would recommend using oidc-client-ts. Here's example code for oidc-client-ts:

import { UserManager } from "oidc-client-ts";

const origin = window.location.origin;
const userMgr = new UserManager({
    authority: "https://login.test.starcommunity.app",
    redirect_uri: origin + "/login",
    scope: "openid email profile",
    client_id: "<YOUR CLIENT ID>"
});

const attemptLogin = async () => {
    const queryParams = new URLSearchParams(window.location.search);
    const code = queryParams.get("code");

    if (code) {
      try {
        await userMgr.signinRedirectCallback(window.location.toString());
        return;
      } catch (e) {
        // TODO: Sometimes your state is already redeemed.
        console.warn(e);
        return;
      }
    }

    const user = await userMgr.getUser();
    if (!user) {
      await userMgr.signinRedirect();
      return;
    }
  };

  (async () => {
    await attemptLogin();

    const user = await userMgr.getUser();
    console.log(user);
  })();

Node.js (backend)​

You can use panva/node-openid-client. Here is a code example for Node.js with this library for the Authorization Code Flow:

import { Issuer, generators } from 'openid-client';

const hubbleIssuer = await Issuer.discover('https://login.test.starcommunity.app');
const callbackUrl = 'http://localhost:3000/cb';
const client = new hubbleIssuer.Client({
  client_id: 'your-client-id',
  redirect_uris: [callbackUrl],
  response_types: ['code'],
});

const code_verifier = generators.codeVerifier();
const code_challenge = generators.codeChallenge(code_verifier);

const authorizationUrl = client.authorizationUrl({
  scope: 'openid email profile example_scope',
  code_challenge,
  code_challenge_method: 'S256',
});

redirect(authorizationUrl);

// For callback route
const params = client.callbackParams(req);
const tokenSet = await client.callback(callbackUrl, params, { code_verifier });
console.log('received and validated tokens %j', tokenSet);
console.log('validated ID Token claims %j', tokenSet.claims());

const userinfo = await client.userinfo(access_token);
console.log('userinfo %j', userinfo);

PHP​

You can use jumbojett/OpenID-Connect-PHP. This is a code example for PHP with this library for the Authorization Code Flow:

use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient('https://login.test.starcommunity.app',
                                'your-client-id',
                                null);
$oidc->setCodeChallengeMethod('S256');
$oidc->addScope(['example_scope']);
$oidc->authenticate();
$name = $oidc->requestUserInfo('name');

Python​

You can use libraries for CLI or Django. Make sure to enable PKCE for the Authorization Code Flow.

info

Other language? Or got stuck? Reach out to us for assistance.

Explanation Video​

This video explains OIDC and might help you get more context.