# OneiD

> OneiD signs users in to your applications and issues tokens. It is an OAuth 2.0 authorization server and OpenID Connect provider with an admin console, multi-factor authentication (TOTP), roles and an audit log. Users come from OneiD accounts, LDAP or Active Directory, or an upstream OpenID Connect provider such as Okta.

Every page below is available as Markdown (the links point to the .md copies). All pages in one file: https://oltinid.com/llms-full.txt. To build an integration, start with the Connector specification. A skill file for coding agents: https://oltinid.com/oneid-skill.md.

## Key facts for agents

- OneiD is an OAuth 2.0 authorization server and OpenID Connect provider. Configure libraries from discovery: `https://YOUR_ONEID/.well-known/openid-configuration`.
- The issuer ends with a slash: `https://YOUR_ONEID/`. Compare `iss` with the discovery value exactly.
- Use the authorization code flow with PKCE (`S256` only) for every application with a user; `client_credentials` for services. Implicit, hybrid, password (ROPC) and device flows are not supported.
- Client authentication: `client_secret_basic` (preferred) or `client_secret_post`. `private_key_jwt` and mTLS cannot be used.
- Access tokens are RS256 JWTs with `iss`, `sub`, `exp`, `scope`, `client_id` and no `aud`. APIs check signature (JWKS), issuer, expiry and the required scope; they must not require an audience.
- Refresh tokens (scope `offline_access`) rotate on every use; store the new one. Reuse after a short grace period revokes the chain.
- Sign-out: RP-initiated logout at `/connect/logout` with `id_token_hint` and a registered `post_logout_redirect_uri`. No front-channel or back-channel logout.
- Clients are registered by an administrator (no dynamic registration). Browser clients need their origin in the client's allowed CORS origins.
- Key users by `iss` + `sub`, never by email. Roles are in the `role` claim (scope `roles`).
- Not supported: SAML, SCIM, PAR, JAR, DPoP, token exchange, CIBA, `login_hint`, `ui_locales`, enforcement of `acr_values` (check `acr`/`amr` in the ID token instead).

## Get started

- [How OneiD works](https://oltinid.com/docs/get-started/overview.md): Learn the parts of OneiD you work with when you connect an application or API, and how a sign-in moves between them.
- [Your first sign-in](https://oltinid.com/docs/get-started/first-sign-in.md): Sign in to the OneiD demo application, read the discovery document of the demonstration instance and pick a quickstart.
- [Choose a flow](https://oltinid.com/docs/get-started/choose-a-flow.md): Answer two questions to find the OAuth 2.0 grant and client type your application needs with OneiD.
- [Register an application](https://oltinid.com/docs/get-started/register-an-application.md): Know what your OneiD administrator enters when registering your application, and send them the values they need.

## Quickstarts

- [Quickstarts](https://oltinid.com/docs/quickstarts.md): Complete, runnable examples that connect an application or an API to OneiD.
- [JavaScript single-page application](https://oltinid.com/docs/quickstarts/javascript.md): Add OneiD to a JavaScript application with oidc-client-ts, step by step.
- [React single-page application](https://oltinid.com/docs/quickstarts/react.md): Add OneiD to a React application with react-oidc-context, step by step.
- [Angular single-page application](https://oltinid.com/docs/quickstarts/angular.md): Add OneiD to a Angular application with oidc-client-ts, step by step.
- [Node.js web application (Express)](https://oltinid.com/docs/quickstarts/node.md): Add OneiD to a Node.js application with openid-client, step by step.
- [ASP.NET Core web application](https://oltinid.com/docs/quickstarts/dotnet.md): Add OneiD to a .NET application with Microsoft.AspNetCore.Authentication.OpenIdConnect, step by step.
- [Go web application](https://oltinid.com/docs/quickstarts/go.md): Add OneiD to a Go application with coreos/go-oidc, step by step.
- [Python web application (Flask)](https://oltinid.com/docs/quickstarts/python.md): Add OneiD to a Python application with Authlib with Flask, step by step.
- [Java web application (Spring Security)](https://oltinid.com/docs/quickstarts/java.md): Add OneiD to a Java application with Spring Security, step by step.
- [Machine to machine with cURL](https://oltinid.com/docs/quickstarts/curl.md): Add OneiD to a cURL service with Client credentials grant, step by step.
- [Protect a Node.js API](https://oltinid.com/docs/quickstarts/api-node.md): Add OneiD to a Node.js API API with jose with Express, step by step.
- [Protect an ASP.NET Core API](https://oltinid.com/docs/quickstarts/api-dotnet.md): Add OneiD to a .NET API API with Microsoft.AspNetCore.Authentication.JwtBearer, step by step.
- [Protect a Go API](https://oltinid.com/docs/quickstarts/api-go.md): Add OneiD to a Go API API with coreos/go-oidc, step by step.
- [Protect a Python API (Flask)](https://oltinid.com/docs/quickstarts/api-python.md): Add OneiD to a Python API API with PyJWT with Flask, step by step.
- [Protect a Java API (Spring Security)](https://oltinid.com/docs/quickstarts/api-java.md): Add OneiD to a Java API API with Spring Security, step by step.

## Guides

- [Authorization code flow with PKCE](https://oltinid.com/docs/guides/authorization-code-pkce.md): Sign users in with OneiD using the authorization code flow with PKCE, from the authorisation request to a validated ID token.
- [Client credentials for services](https://oltinid.com/docs/guides/client-credentials.md): Get an access token for a service, job or daemon that calls an API without a user, and reuse it until it is about to expire.
- [Refresh tokens](https://oltinid.com/docs/guides/refresh-tokens.md): Keep users signed in beyond the access token lifetime with OneiD refresh tokens, and handle rotation, reuse and failures correctly.
- [Sign-out](https://oltinid.com/docs/guides/logout.md): Sign users out of your application and OneiD with RP-initiated logout, and design for applications that are not notified.
- [Sessions, prompt and max_age](https://oltinid.com/docs/guides/sessions-and-reauthentication.md): Control when OneiD asks users to sign in again, check sessions silently, and require a recent or MFA sign-in for sensitive actions.
- [Browser applications and CORS](https://oltinid.com/docs/guides/browser-applications.md): Connect a single-page application to OneiD as a public client, store tokens safely, renew them in the background and fix CORS errors.
- [Mobile and desktop applications](https://oltinid.com/docs/guides/native-applications.md): Sign users in to a mobile or desktop app with OneiD using the system browser, PKCE and a private-use or loopback redirect URI.
- [Protect an API (validate access tokens)](https://oltinid.com/docs/guides/protect-an-api.md): Validate OneiD access tokens in your API by checking the signature, issuer, expiry and scope, and answer with the right 401 or 403.
- [Scopes, claims and roles](https://oltinid.com/docs/guides/scopes-claims-roles.md): Request the right scopes, read the claims OneiD releases for them, and use roles from OneiD for authorisation in your application.
- [Security best practices](https://oltinid.com/docs/guides/security-best-practices.md): Check your OneiD integration against a list of practices for flows, secrets, tokens, sessions and APIs before you go live.

## Reference

- [Endpoints](https://oltinid.com/docs/reference/endpoints.md): Every OneiD protocol endpoint with its method, path, authentication, parameters, example request and response, and errors.
- [Discovery document](https://oltinid.com/docs/reference/discovery.md): Read OneiD's OpenID Connect discovery document field by field and know which advertised options to use.
- [Tokens](https://oltinid.com/docs/reference/tokens.md): Understand the ID tokens, access tokens, refresh tokens and codes OneiD issues, their lifetimes, signing keys and how to validate them.
- [Claims](https://oltinid.com/docs/reference/claims.md): Look up every claim OneiD issues, where it appears, which scope releases it, and how to use the claims request parameter.
- [Errors and troubleshooting](https://oltinid.com/docs/reference/errors.md): Recognise every error OneiD returns, where it appears and what to change, and fix the most common integration problems.
- [Rate limits](https://oltinid.com/docs/reference/rate-limits.md): Know which OneiD endpoints are rate limited, the token endpoint defaults, the 429 response and how to retry correctly.
- [Client settings](https://oltinid.com/docs/reference/client-settings.md): See every setting an administrator can set on a OneiD client, what each one controls and the rules OneiD applies to it.
- [Standards support](https://oltinid.com/docs/reference/standards-support.md): Check which OAuth 2.0 and OpenID Connect standards and features OneiD supports, which it does not, and what to use instead.

## Sign-in sources

- [Where users come from](https://oltinid.com/docs/sign-in-sources/overview.md): Understand the sign-in sources a OneiD deployment can use, what users see with each, and how groups become roles.
- [OneiD accounts and MFA](https://oltinid.com/docs/sign-in-sources/oneid-accounts.md): Learn how OneiD accounts are created, how passwords, lockout, recovery and MFA work, and what users and administrators can do.
- [LDAP and Active Directory](https://oltinid.com/docs/sign-in-sources/ldap.md): Prepare your directory so OneiD can sign users in with their directory accounts, and decide how directory groups become roles.
- [Okta and other OpenID Connect providers](https://oltinid.com/docs/sign-in-sources/openid-connect-provider.md): Register OneiD at Okta or another OpenID Connect provider so users sign in there, and map the provider's groups to roles.

## AI agents

- [Build with AI coding agents](https://oltinid.com/docs/ai/build-with-ai.md): Give an AI coding agent the OneiD documentation in a form it can read, and use ready-made prompts to add sign-in or protect an API.
- [Connector specification](https://oltinid.com/docs/ai/connector-specification.md): The normative rules a OneiD connector for any framework, product, gateway or SaaS must follow, with a conformance checklist and tests.

## Operate OneiD

- [Run OneiD in your own environment](https://oltinid.com/docs/operate/overview.md): Compare OneiD hosted by us with running it yourself, and see what your own environment needs for running, scaling and backups.
- [Automate with the Admin API](https://oltinid.com/docs/operate/admin-api.md): Get an overview of the OneiD Admin API, how to authenticate to it, what it manages and which administrator roles it respects.

## Optional

- [Product overview](https://oltinid.com/product/): features, sign-in sources and standards
- [Security](https://oltinid.com/security/): how OneiD protects accounts, keys and tokens
- [Demonstration application](https://demo.oltinid.com): signs in through the demonstration instance https://auth.oltinid.com