Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / identity-provider-integration

Identity provider integration

Identity provider integration lets Memos use an external OAuth2 service for sign-in and for linking an external account to an existing Memos account. Administrators define the provider and its claim mapping. Memos then exchanges an authorization code for user data and resolves that data to a local user. See Identity, authentication, and access control for the wider authentication model.

Provider configuration

An identity provider is a named OAuth2 connection that supplies the URLs, client credentials, requested scopes, and user-data mapping needed for an external sign-in. Memos currently exposes OAuth2 as the provider type, with a stable resource name in the form identity-providers/{idp}.

Provider resource

The provider resource has a display title and a stable identifier called the provider UID. It can also have an identifier filter. The filter limits which external subjects may use that provider before Memos looks up or creates a local account.

OAuth2 configuration maps four kinds of external data:

ConfigurationPurpose
Client ID and client secretIdentify Memos to the external provider
Authorization, token, and user-info URLsDefine the OAuth2 exchange and user-data requests
ScopesRequest the claims needed from the provider
Field mappingMap the external subject, display name, email, and avatar claims

The external subject mapping is required because it is the durable identity key used for account resolution. Display name, email, and avatar are optional inputs for the local user profile. The client secret is write-only in API responses.

References: proto/…/idp.proto• L7-42 proto/…/idp_service.proto• L51-104 server/…/idp_service.go• L211-218

Deployment configuration

Providers can be stored as administrator-managed resources or supplied as deployment configuration. A deployment file contains one provider with its UID and OAuth2 settings. The runtime provider with that UID takes precedence over a stored provider, while existing user links continue to use the UID.

Deployment configuration is read when the server starts. A changed file needs a restart. API actions cannot update or delete a provider that is managed by the deployment. For file names, validation, secrets, and rollout behavior, see Configuration provisioning and Deployment configuration and operations.

References: docs/configuration-provisioning.md• L21-34 docs/configuration-provisioning.md• L72-84 docs/configuration-provisioning.md• L121-164 docs/configuration-provisioning.md• L339-351

Provider management

Administrators manage stored providers through the identity-provider service. The service lists effective providers for public sign-in pages and permits create, update, and delete actions only for an authenticated administrator. Updates keep the provider UID stable, so changing a title or connection setting does not move existing account links.

Provider updates validate the complete resulting resource rather than only the fields in the update request. If an edit omits the write-only client secret, Memos keeps the stored secret. Deployment-managed providers cannot be changed through the API, and deletion is blocked when it would leave the instance with an unsafe authentication setup.

The web settings page provides templates for GitHub, GitLab, and Google, plus a custom OAuth2 connection. The form collects the provider ID, connection URLs, scopes, claim names, and optional identifier filter. It also shows the callback URL that must be registered with the external provider. When an existing provider is edited, the client secret can remain unchanged.

References: proto/…/idp_service.proto• L14-49 server/…/idp_service.go• L19-208 web/…/SSOSection.tsx• L34-115 web/…/CreateIdentityProviderDialog.tsx• L25-123 web/…/CreateIdentityProviderDialog.tsx• L263-388 web/…/CreateIdentityProviderDialog.tsx• L406-610

OAuth2 sign-in

Memos uses the OAuth2 authorization-code flow. The browser starts at the external provider, returns to the Memos callback, and sends the authorization code to the server. The server performs the token exchange and user-info request so the external access token is not used as a Memos session token.

Authorization request

The sign-in page loads the effective provider list and shows one button per provider. Selecting a provider sends the browser to its authorization URL with the Memos callback URI, the provider client ID, the requested scopes, and a random state value. When automatic sign-in is enabled and exactly one provider has a valid OAuth2 configuration, Memos starts the same flow without a button press and records that the automatic attempt has started.

The browser stores the state with the provider name and a safe return path in session storage. When the browser has the required secure cryptography APIs, it also creates a PKCE verifier and sends its SHA-256 challenge. On a context without those APIs, the flow falls back to OAuth2 without PKCE and warns that HTTPS provides stronger protection.

While a redirect is pending, the sign-in page shows the selected provider and prevents another sign-in attempt through both its visible state and an immediate in-memory guard. The automatic path marks the page for manual sign-in before navigation, so a browser Back action or reload does not repeat the automatic redirect. A restored page clears its pending state, and an error while starting the flow returns control to the sign-in page.

References: web/…/SignIn.tsx• L13-61 web/…/IdentityProviderButtons.tsx• L18-101 web/…/sso.ts• L7-40 web/…/oauth.ts• L1-98

Callback and token exchange

The callback route is /auth/callback. It first checks for an error from the external provider, then requires both the authorization code and state. State validation checks the stored value and its ten-minute lifetime, removes it after use, and returns the provider, flow mode, return path, and optional PKCE verifier.

For sign-in, the callback sends the code, callback URI, and verifier to AuthService.SignIn. The server finds the configured provider by UID, exchanges the code for an access token, and requests JSON user information with that token. The configured field mapping produces an external subject plus optional profile values.

After Memos resolves the local user, it creates the normal Memos session. The response carries a short-lived access token. A refresh token is kept in an HttpOnly cookie and is rotated by the normal session flow.

This sequence shows how the browser callback becomes a Memos session.

sequenceDiagram
    participant B as Browser
    participant P as External provider
    participant M as Memos server
    participant D as Memos data store

    B->>M: List effective providers
    M-->>B: Provider title and OAuth2 settings
    B->>B: Store state and optional PKCE verifier
    B->>P: Authorization request
    P-->>B: Redirect with code and state
    B->>B: Validate state and recover verifier
    B->>M: SignIn(code, provider, callback URI, verifier)
    M->>P: Exchange code for access token
    P-->>M: Access token
    M->>P: Request user info
    P-->>M: Mapped external subject and profile data
    M->>D: Resolve or create local user
    M-->>B: Memos access token and refresh cookie

References: web/…/AuthCallback.tsx• L19-137 web/…/oauth.ts• L100-160 server/…/auth_service.go• L42-107 server/…/auth_service_sso.go• L140-183 internal/…/oauth2.go• L19-141 server/…/auth_service_session.go• L24-62

User identity linking

A linked identity binds one external subject to one Memos account. Memos uses the pair of provider UID and external subject as the link key. This keeps external account identity separate from a mutable Memos username.

Existing account lookup

At SSO sign-in, Memos first searches the identity link for the provider UID and external subject. A match returns the linked local user. An external subject is never treated as a local username unless Memos is creating a new account and the subject also satisfies local username rules.

The link rules protect account ownership:

SituationResult
Provider and external subject already link to this userSign-in succeeds
Provider and external subject link to another userThe request is rejected
The subject is emptyThe request is rejected
The provider filter does not matchThe request is rejected

References: server/…/auth_service_sso.go• L20-42 server/…/auth_service_sso.go• L193-236 store/user_identity.go• L5-23 store/…/00__user_identity.sql• L1-15

First SSO sign-in

When no link exists, Memos checks the instance registration policy. If registration is open, it creates a local user and the identity link together. The external identifier becomes the preferred username when it passes local username rules and is available. Otherwise Memos uses an opaque generated username.

The new account receives the mapped display name and avatar. Memos uses the mapped email only when it is valid and is not already held by another local account. Its generated local password is not the source of SSO authentication. The identity link remains the authority for later SSO lookups.

References: server/…/auth_service_sso.go• L44-190 store/user_identity.go• L32-47 store/…/user_identity.go• L55-76

Account linking flow

An authenticated user can link an external account from account settings without creating another Memos user. The page loads the effective provider set and the current user's links, then shows one row for each effective OAuth2 provider with its type, provider UID, and link status. It shows the external UID when a link exists. The browser records a link flow mode and the current Memos username in OAuth state. The callback checks that the same user is still signed in, then calls the linked-identity API with the authorization code.

The server applies the same provider lookup, token exchange, claim mapping, and identifier filter used by sign-in. It then adds the link to the current user. A user can have links to several providers but only one external account for each provider. An external account that already belongs to another Memos user cannot be taken over.

The account settings page can start linking or remove an existing link. A link managed by deployment configuration is shown as managed and cannot be removed from the page. The managed marker and removal rule apply to the linked identity resource, while an unlinked provider still offers a link action. The linked identity response exposes the provider resource and external identifier, not the provider secret.

References: web/…/LinkedIdentitySection.tsx• L30-143 web/…/LinkedIdentitySection.tsx• L145-196 web/…/AuthCallback.tsx• L79-124 proto/…/user_service.proto• L94-119 proto/…/user_service.proto• L533-612 server/…/user_service_identities.go• L14-134 server/…/auth_service_sso.go• L260-311

Authentication policy

SSO and password sign-in are separate methods controlled by the instance general settings. An administrator can disable password sign-in for regular users when an effective identity provider is available. The administrator password path remains available so the instance can be recovered.

If registration is disabled, a first SSO login cannot create a local account. If password sign-in is disabled and no provider is available, the web sign-in and sign-up pages show an unavailable state instead of presenting a dead flow. The server also protects provider deletion and authentication-setting changes that would leave regular users without a usable sign-in method.

For the related account and instance controls, see Web settings and account management.

References: server/…/auth_service.go• L54-95 server/…/auth_service_sso.go• L44-65 web/…/SignIn.tsx• L15-61 web/…/SignUp.tsx• L24-163 web/…/InstanceSection.tsx• L146-179 docs/configuration-provisioning.md• L368-405

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the provider UID stable when changing provider display data or connection settings. User links and SSO lookup both depend on that UID.
  • Keep the callback route, registered redirect URI, browser authorization request, and server token exchange aligned. A mismatch breaks every OAuth2 login.
  • Update the field mapping and requested scopes together. The mapped identifier is required for account lookup and first-login provisioning.
  • Preserve the distinction between sign-in and link flow state. A callback that treats a link as sign-in can create or select the wrong local account.
  • Keep automatic single-provider sign-in aligned with the manual sign-in path. Changes to provider validation, redirect state, or browser history handling can cause repeated redirects or block manual recovery.
  • When changing registration or password policy, check the effective provider set. Deployment providers shadow stored providers and can change whether the instance has a usable fallback.
  • Keep provider-secret redaction intact across API conversion, settings views, errors, and deployment startup diagnostics.
  • Keep provider update validation based on the merged resource. A partial update must not bypass required OAuth2 fields or replace an omitted client secret with an empty one.
  • Keep provider deletion checks aligned with the effective authentication policy. Removing a provider must not leave regular users without a usable sign-in method.
  • Keep linked-identity settings aligned with deployment ownership. A configuration-managed link must remain visible but must not expose an unlink action.

Important failure modes

TriggerConsequenceGuard
OAuth callback state is missing, expired, or does not match session stateThe callback stops before token exchangeState is single-use, time-limited, and checked before the code is sent to the server
Provider returns no mapped external subjectMemos cannot resolve or safely create a userThe OAuth2 adapter and SSO resolution path require the configured identifier claim to be non-empty
The external subject is already linked to another Memos userSign-in or linking is rejected instead of moving the linkProvider UID and external subject are unique, and link ownership is checked
Automatic sign-in is enabled without exactly one valid providerMemos does not redirect automatically, so the user must choose a providerAutomatic sign-in requires one provider with a valid OAuth2 configuration
A sign-in attempt is started more than once before navigationDuplicate OAuth2 redirects are not startedThe sign-in page uses an immediate redirect guard, tracks a pending provider, and disables the provider buttons
Password sign-in is disabled without an effective providerRegular users lose a sign-in pathStartup and runtime policy checks reject unsafe effective authentication state
A deployment-managed provider is changed through the APIThe stored change would be hidden by the runtime providerThe provider mutation returns a failed-precondition response
The provider returns a non-success user-info response or malformed JSONSSO resolution fails and no Memos session is createdThe server checks the HTTP response and parses the mapped claims before user resolution
A mapped email is invalid or belongs to another accountThe new SSO account is created without that emailEmail normalization and ownership checks prevent an external claim from taking an existing local email
A provider update omits the client secret and validates only the changed fieldsA valid provider can lose its credential or accept an incomplete configurationThe service merges the update with the stored provider, preserves the secret, and validates the resulting resource
A provider deletion would remove the last usable regular-user sign-in methodRegular users can no longer sign inSafe deletion rejects the change when the effective authentication configuration would be unsafe
A user tries to unlink a configuration-managed identityThe link cannot be removed through account settingsThe settings page identifies managed resources and hides the unlink action

Key files

FileWhy to read it
proto/…/idp.protoDefines the stored provider shape, OAuth2 fields, and claim mapping.
proto/…/idp_service.protoDefines the provider resource and administrator API contract.
proto/…/auth_service.protoDefines password and SSO sign-in inputs, including the callback URI and PKCE verifier.
proto/…/user_service.protoDefines linked-identity resources and link management operations.
server/…/idp_service.goShows provider management, update validation, deployment ownership checks, safe deletion, and secret handling.
internal/…/oauth2.goShows the provider-facing authorization-code exchange and user-info mapping boundary.
server/…/auth_service_sso.goShows external identity resolution, first-login provisioning, email safeguards, and link ownership rules.
server/…/user_service_identities.goShows the user-facing list, link, get, and unlink operations.
web/…/IdentityProviderButtons.tsxShows how manual and automatic sign-in begin, how duplicate attempts are prevented, and how OAuth2 state is attached.
web/…/AuthCallback.tsxShows how the browser callback selects sign-in or account linking.
web/…/LinkedIdentitySection.tsxShows how users view and manage external account links, including configuration-managed links.
web/…/SSOSection.tsxShows how administrators view and manage configured providers.
web/…/CreateIdentityProviderDialog.tsxShows provider templates, callback URL guidance, and the fields used to create or update OAuth2 providers.
web/…/oauth.tsShows the short-lived browser state used for CSRF protection and callback recovery.