User Authentication in Elements

Elements provides multiple ways to create and authenticate users, depending on your needs. You can use simple username/email + password logins, or integrate with third-party identity providers like Google or Steam via OIDC and OAuth2.

---

Authentication Methods #

1. Password Users #

The most straightforward approach: create an account with a username/email and a password.

There are two ways to create password-based users:

• Admin creation (requires SUPERUSER session token):
  • POST /api/rest/users
  • Used by administrators to manually create users.
  • Must include a valid session token with SUPERUSER privileges.
• Public signup (no authentication required):
  • POST /api/rest/signup
  • End users can sign up themselves with just a username/email and password.
  • No prior authentication required.

Once created, users can log in with their credentials and receive a session token.

---

2. OIDC (OpenID Connect) with JWTs #

OIDC lets users authenticate with external providers (like Google) using JWTs (JSON Web Tokens).

Setup steps:

1. Create an Auth Scheme for the provider:
   • Give it a name (e.g. Google).
   • Provide the JWK URL (JSON Web Key Set) from the provider.
2. When a user tries to log in:
   • The client sends the JWT obtained from the provider to Elements.
   • Elements uses the JWK to verify the token’s signature.
   • If valid:
     • A user account is created automatically if one doesn’t already exist.
     • A session token is returned.

Key point: OIDC login requires no password handling on your end. Elements verifies identity using the provider’s JWT.

---

3. OAuth2 (Customizable) #

OAuth2 is a flexible alternative to OIDC, useful for providers like Steam that don’t offer standard OIDC.

Setup steps:

1. Create an Auth Scheme:
   • Name (e.g. Steam).
   • Validation URL (where Elements verifies the token).
   • User ID property (the field in the validation response that maps to a user ID, e.g. steamid).
   • Custom headers or query parameters (if the provider requires them).
   • Specify whether parameters are:
     • Sent by the frontend (dynamic, provided per login request), or
     • Pre-set in the auth scheme (static, stored securely).
2. Login flow:
   • The frontend collects the OAuth2 token from the provider.
   • Sends it to Elements along with the scheme name.
   • Elements calls the validation URL, passes required headers/params, and checks the response.
   • If valid:
     • A user is created if needed.
     • A session token is returned.

---

Quick Comparison #

Method	When to Use	Requirements	Flow
Password	Simple accounts with username/email + password	Admin token (for manual creation) OR none (for signup)	POST request to Elements; returns session token
OIDC	Standard identity providers (Google, Apple, etc.)	Create Auth Scheme with JWK URL	Client provides JWT → Elements verifies → returns session token
OAuth2	Providers without OIDC (Steam, custom services)	Create Auth Scheme with validation URL, user ID mapping, headers/params	Client provides token → Elements validates → returns session token

---

Best Practices #

• Use OIDC when possible — it’s simpler and more standardized than custom OAuth2.
• For password users, prefer the public signup endpoint to avoid handling SUPERUSER tokens unnecessarily.
• Keep Auth Scheme configs secure. Only expose parameters the frontend needs to send dynamically.
• Treat session tokens like sensitive credentials — they grant access to the user’s account.

---

See Also #

• Elements API Reference: /api/users
• Elements API Reference: /api/signup
• Auth Scheme Configuration