--- title: User Authentication in Elements description: "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](https://namazustudios.com/glossary/oidc/)** and **[OAuth2](https://namazustudios.com/glossary/oauth2/)**. --- ## Authentication Methods ###…" url: "https://namazustudios.com/docs/namazu-elements-core/user-authentication-sign-in/user-authentication-in-elements/" updated: "2026-08-15" category: Namazu Elements Core Features / User Authentication / Sign In --- # 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](https://namazustudios.com/glossary/oidc/)** and **[OAuth2](https://namazustudios.com/glossary/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](https://namazustudios.com/glossary/session/) token):** - `POST /api/REST/users` - Used by administrators to manually create users. - Must include a valid [Session](https://namazustudios.com/glossary/session/) token with SUPERUSER privileges. - **Public signup (no authentication required):** - `POST /api/REST/signup`/ - Alternatively - `POST /api/REST/signup/Session` to create a [Session](https://namazustudios.com/glossary/session/) when signing up so that you don't need to make a second request to sign in (Elements 3.7+) - End users can sign up themselves with just a username/email and password. - No prior authentication required. - Can create a [Profile](https://namazustudios.com/glossary/profile/) within the same request. Once created, users can log in with their credentials and receive a **[Session](https://namazustudios.com/glossary/session/) token**. --- ### 2. [OIDC](https://namazustudios.com/glossary/oidc/) (OpenID Connect) with JWTs [OIDC](https://namazustudios.com/glossary/oidc/) lets users authenticate with external providers (like Google) using **JWTs** (JSON Web Tokens). **Setup steps:** 1. Create an **[Auth Scheme](https://namazustudios.com/docs/namazu-elements-core/user-authentication-sign-in/auth-schemes/oidc/)** for the provider: - Give it a [name](https://namazustudios.com/glossary/name/) (e.g. `Google`). - Provide the **JWK URL** (JSON Web Key Set) from the provider. 2. When a [User](https://namazustudios.com/glossary/user/) tries to log in: - The client sends the [JWT](https://namazustudios.com/glossary/jwt/) obtained from the provider to Elements. - Elements uses the JWK to verify the token’s signature. - If valid: - A [User](https://namazustudios.com/glossary/user/) account is created automatically if one doesn’t already exist. - A [Session](https://namazustudios.com/glossary/session/) token is returned. **Key point:** [OIDC](https://namazustudios.com/glossary/oidc/) login requires **no password** handling on your end. Elements verifies identity using the provider’s [JWT](https://namazustudios.com/glossary/jwt/). *(Elements 3.9+)* Rather than passing an explicit `profileId` or `profileSelector`, username/password and [OAuth2](https://namazustudios.com/glossary/oauth2/) [Session](https://namazustudios.com/glossary/session/) requests can instead pass `applicationNameOrId` to have Elements attach the [User](https://namazustudios.com/glossary/user/)'s primary [Profile](https://namazustudios.com/glossary/profile/) for that [Application](applications) automatically -- see [Sessions](sessions) for details. --- ### 3. [OAuth2](https://namazustudios.com/glossary/oauth2/) (Customizable) [OAuth2](https://namazustudios.com/glossary/oauth2/) is a flexible alternative to [OIDC](https://namazustudios.com/glossary/oidc/), useful for providers like **Steam** that don’t offer standard [OIDC](https://namazustudios.com/glossary/oidc/). **Setup steps:** 1. Create an **[Auth Scheme](https://namazustudios.com/docs/namazu-elements-core/user-authentication-sign-in/auth-schemes/oauth2/)**: - **[name](https://namazustudios.com/glossary/name/)** (e.g. `Steam`). - **Validation URL** (where Elements verifies the token). - **[User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) property** (the field in the validation response that maps to a [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/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](https://namazustudios.com/glossary/oauth2/) token from the provider. - Sends it to Elements along with the scheme [name](https://namazustudios.com/glossary/name/). - Elements calls the validation URL, passes required headers/params, and checks the response. - If valid: - A [User](https://namazustudios.com/glossary/user/) is created if needed. - A [Session](https://namazustudios.com/glossary/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](https://namazustudios.com/glossary/session/) token | | **[OIDC](https://namazustudios.com/glossary/oidc/)** | Standard identity providers (Google, Apple, etc.) | Create Auth Scheme with JWK URL | Client provides [JWT](https://namazustudios.com/glossary/jwt/) → Elements verifies → returns [Session](https://namazustudios.com/glossary/session/) token | | **[OAuth2](https://namazustudios.com/glossary/oauth2/)** | Providers without [OIDC](https://namazustudios.com/glossary/oidc/) (Steam, custom services) | Create Auth Scheme with validation URL, [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) mapping, headers/params | Client provides token → Elements validates → returns [Session](https://namazustudios.com/glossary/session/) token | --- ## Best Practices - Use **[OIDC](https://namazustudios.com/glossary/oidc/)** when possible — it’s simpler and more standardized than custom [OAuth2](https://namazustudios.com/glossary/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](https://namazustudios.com/glossary/session/) tokens** like sensitive credentials — they grant access to the [User](https://namazustudios.com/glossary/user/)’s account. --- ## See Also - [Elements API Reference: `/api/users`](https://namazustudios.com/rest/api/#/operations/createUser) - [Elements API Reference: `/api/signup`](https://namazustudios.com/rest/api/#/operations/createUsernamePasswordSession) - [Auth Scheme Configuration](https://namazustudios.com/docs/core-features/auth-schemes/auth-schemes/)