OAuth with Authentik

Authentik is an open source identity provider that you run on your own infrastructure. It provides single sign-on over OAuth 2.0, OpenID Connect, SAML, and LDAP, along with configurable flows for enrollment, recovery, and multi-factor authentication.

How does the integration work?

You can use the Authentik OAuth adapter in Appwrite Auth to sign users in through your Authentik instance. Appwrite redirects users to your instance's authorization endpoint, exchanges the authorization code for tokens, and creates an Appwrite user from the OpenID Connect user info. Your users keep a single identity in Authentik, and your app gets Appwrite sessions, permissions, and APIs on top of it.

Appwrite requests the openid, profile, and email scopes, plus offline_access for a refresh token. It marks the user's email as verified only when Authentik returns email_verified as true.

Prerequisites

• A running Authentik instance served over HTTPS. Appwrite calls its token and user info endpoints from the server, so the instance must be reachable from your Appwrite project.
• An Authentik account with access to the admin interface.

How to implement

To implement the Authentik OAuth adapter in Appwrite Auth, there are several steps you must complete:

Step 1: Create an OAuth2/OpenID provider in Authentik

In the Authentik admin interface, create an application backed by an OAuth2/OpenID Provider. Authentik's application wizard can create the application and its provider in one flow.

Configure the provider as follows:

• Set the client type to Confidential, since Appwrite exchanges codes with a client secret.
• Leave the redirect URI for now. You'll add the exact URI from Appwrite in the next step.
• If you want Appwrite to receive refresh tokens, add the offline_access scope mapping to the provider. Since Authentik 2024.2, applications receive only an access token by default.

Save the provider and copy its Client ID and Client Secret.

Step 2: Add Authentik OAuth adapter to your Appwrite project

For this step, you must create an account on Appwrite Cloud or self-host Appwrite if you haven't already. In your Appwrite project, head over to the Auth page, open the Settings tab, and click Authentik under the OAuth2 Providers section.

Fill in the provider form:

• Client ID: the provider's Client ID.
• Client Secret: the provider's Client Secret.
• Domain: the host name of your Authentik instance without https://, for example example.authentik.com. Appwrite builds the endpoints from it, such as https://example.authentik.com/application/o/authorize/.

Turn the provider on and click Update. Appwrite won't enable the provider until the Domain field is set.

Copy the Redirect URI shown in the form. On Appwrite Cloud it looks like https://<REGION>.cloud.appwrite.io/v1/account/sessions/oauth2/callback/authentik/<PROJECT_ID>, but always copy the exact value from the Console. In Authentik, edit the provider and add it to its Redirect URIs.

Step 3: Test the provider

Start a session from your app with the OAuthProvider.Authentik value. With the Web SDK:

import { Client, Account, OAuthProvider } from 'appwrite';

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const account = new Account(client);

account.createOAuth2Session({
    provider: OAuthProvider.Authentik,
    success: 'https://example.com/success',
    failure: 'https://example.com/failed',
});

Add your app's domain as a web platform in your Appwrite project so Appwrite accepts the success and failure URLs. Follow the OAuth 2 login flow for other platforms and for server-side sign-in.

Read more about Authentik and Appwrite Auth

If you would like to learn more about Authentik and Appwrite Auth, we have some resources that you should visit: