---
title: Auth.js | Integrations
keywords: 'authentication, auth, oauth'
contributors:
  - saisrikardumpeti
  - ulic75
  - jakovljevic-mladen
  - ayoub9494
  - igorbabko
  - yaikohi
  - mrhoodz
  - VinuB-Dev
  - hugomonte
  - VarPDev
  - cwoolum
updated_at: '2023-10-15T10:10:17Z'
created_at: '2023-04-24T10:35:21Z'
---

import PackageManagerTabs from '~/components/package-manager-tabs/index.tsx';
import { Note, LongNote } from '~/components/note/note';

# Auth.js

[Auth.js](https://authjs.dev/) is a well-known library for authentication used by various JS frameworks. With Auth.js, we benefit from reduced complexity. We also have access to a range of authentication providers, such as GitHub, Google, Facebook, among others. Moreover, it can be integrated into multiple frameworks including Qwik.

Auth.js offers several features that enhance simplicity, productivity, flexibility, and provider diversity. Here are the main features of Auth.js:

- **Providers**: Auth.js supports multiple providers, simplifying the authentication process in our applications (e.g., Github, Google, Facebook, Twitter). It also offers Single Sign-On (SSO) services as well as traditional authentication.
- **Management**: Auth.js greatly assists us in concentrating on our business logic. It manages tokens, stores them, and refreshes them automatically.
- **Configuration**: Configuring Auth.js is straightforward. It offers easy installation, error handling, custom forms for login and registration, and effortless integration with providers.
- **Integrations**: Auth.js seamlessly integrates with JS frameworks, aided by its comprehensive documentation that provides a clear guide to follow.
- **Security**: While Auth.js is developer-friendly, it's essential to recognize the underlying complexity that ensures a high level of security for our data.

Be aware that the Auth.js library is still in a pre-1.0 stage and could have bugs.

## Installation

You can add Auth.js easily by using the following Qwik starter script:

<PackageManagerTabs>
<span q:slot="pnpm">
```shell
pnpm run qwik add auth
```
</span>
<span q:slot="npm">
```shell
npm run qwik add auth
```
</span>
<span q:slot="yarn">
```shell
yarn run qwik add auth
```
</span>
<span q:slot="bun">
```shell
bun run qwik add auth
```
</span>
</PackageManagerTabs>

This command will add a new package:

- `@auth/qwik`

and create a new file named `plugin@auth.ts` with an example configuration.

<LongNote title="Manual Deployments with Node">
When deploying applications manually using Node.js, particularly with frameworks like Express, the server or Node process does not inherently know if it's being served under HTTP or HTTPS.
Unlike hosting services like Vercel, Netlify, or Cloudflare, where the ORIGIN configuration is automatically managed, manual setups require explicit specification. To ensure that your Node.js application recognizes the correct protocol and host it is being served under, set the following **environment variables**:

-	ORIGIN: Set this to the URL of your application. For example:
	ORIGIN=https://your-app-name.example.com
- PROTOCOL_HEADER: This is used to indicate the original protocol requested by the client. Commonly, this is specified in proxy configurations. Set this variable to:
	PROTOCOL_HEADER=X-Forwarded-Proto
- HOST_HEADER: This header helps identify the original host requested by the client. It is particularly necessary when your Node environment is behind a proxy or load balancer. Set this variable to:
	HOST_HEADER=X-Forwarded-Host
</LongNote>

### Migrating from `@builder.io/qwik-auth`

When migrating from `@builder.io/qwik-auth` to `@auth/qwik`, there are a couple changes that need to be made.

1. The routes provided by the auth library are no longer prefixed with `/api`. If your are using previous guidance for protected routes or calling the auth routes directly, please be sure to update accordingly.

    ```diff
    export const onRequest: RequestHandler = (event) => {
      const session: Session | null = event.sharedMap.get('session');
      if (!session || new Date(session.expires) < new Date()) {
    -    throw event.redirect(302, `/api/auth/signin?redirectTo=${event.url.pathname}`);
    +    throw event.redirect(302, `/auth/signin?callbackUrl=${event.url.pathname}`);
      }
    };
    ```

2. The setup function and and methods exported by it have changed in `plugin@auth.ts`. Be sure to update the imports for the `useAuthSession`, `useAuthSignin`, and `useAuthSignout` methods anywhere you use them in your app.

    ```diff
    import Auth0Provider from "@auth/core/providers/auth0";
    -import { serverAuth$ } from "@builder.io/qwik-auth";
    +import { QwikAuth$ } from "@auth/qwik";

    -export const { onRequest, useAuthSession, useAuthSignin, useAuthSignout } =
    -  serverAuth$(({ env }) => ({
    +export const { onRequest, useSession, useSignIn, useSignOut } = 
    +  QwikAuth$(({ env }) => ({
   ```
3. Update your `vite.config.ts` to include `"@auth/qwik"` to avoid potentials import issues
```diff 
   export default defineConfig(({ command, mode }): UserConfig => {
  return {
    plugins: [qwikCity(), qwikVite(), tsconfigPaths({ root: '.' })],
    // This tells Vite which dependencies to pre-build in dev mode.
    optimizeDeps: {
      include: ["@auth/qwik"],
    },
```


## Qwik API

### useSession

A [routeLoader$](/docs/route-loader/) that returns a session object or an empty object if there is no session. The contents of the session object that is returned are configurable with the session callback. Session data can also be retrieved using the [session](#session) REST API.

```tsx
import { component$ } from '@qwik.dev/core';
import { useSession } from '~/routes/plugin@auth';

export default component$(() => {
  const session = useSession();
  return <p>{session.value?.user?.email}</p>;
});

```

### useSignIn

A [routeAction$](/docs/action/) used to initiate a signin flow or send the user to the signin page listing all possible providers. The CSRF token is handled internally when signing in using `useSignIn`.

#### Parameters

* `providerId`: An optional string parameter with the name of the provider. When supplied will initiate the Authorization Request to your Identity Provider. When omitted will redirect to the built-in/unbranded sign-in page.
* `options`: An optional object of options.
  * `redirectTo`: An optional string specifying to which URL the user will be redirected after signing in. Defaults to the page URL the sign-in is initiated from.
* `authorizationParams`: An optional object of additional parameters sent to the /authorize endpoint. See the Authorization Request OIDC spec for some ideas.

<Note>You can also set the `authorizationParams` through the provider.authorizationParams configuration</Note>

Example using `useSignIn` with the [&lt;Form&gt;](/docs/action/#using-actions-with-form) component and optional `providerId` and `options.redirectTo`:

```tsx
import { component$ } from '@qwik.dev/core';
import { Form } from '@qwik.dev/router';
import { useSignIn } from '~/routes/plugin@auth';

export default component$(() => {
  const signIn = useSignIn();
  return (
    <Form action={signIn}>
      <input type="hidden" name="providerId" value="github" />
      <input type="hidden" name="options.redirectTo" value="http://qwik-auth-example.com/dashboard" />
      <button>Sign In</button>
    </Form>
  );
});
```

Example using `useSignIn` programmatically with optional `providerId` and `options.redirectTo`:

```tsx
import { component$ } from '@qwik.dev/core';
import { useSignIn } from '~/routes/plugin@auth';

export default component$(() => {
  const signIn = useSignIn();
  return (
    <button onClick$={() => signIn.submit({ providerId: 'github', options: { redirectTo: 'http://qwik-auth-example.com/dashboard' } })}>Sign In</button>
  );
});
```

### useSignOut

A [routeAction$](/docs/action/) used to initiate a signout flow. The user session will be invalidated/removed from the cookie/database, depending on the flow you chose to store sessions.

#### Parameters

* `redirectTo`: An optional string specifying to which URL the user will be redirected after signing out. Defaults to the page URL the sign-in is initiated from.

The 'redirectTo' must be considered valid by the redirect callback handler. By default, it requires the URL to be an absolute URL at the same host name, or you can also supply a relative URL starting with a slash. If it does not match it will redirect to the homepage. You can define your own redirect callback to allow other URLs.

Example using `useSignOut` with the [&lt;Form&gt;](/docs/action/#using-actions-with-form) component and optional `redirectTo`:

```tsx
import { component$ } from '@qwik.dev/core';
import { Form } from '@qwik.dev/router';
import { useSignOut } from '~/routes/plugin@auth';

export default component$(() => {
  const signOut = useSignOut();
  return (
    <Form action={signOut}>
      <input type="hidden" name="redirectTo" value="/signedout" />
      <button>Sign Out</button>
    </Form>
  );
});
```

Example using `useSignOut` programmatically with optional `redirectTo`:

```tsx
import { component$ } from '@qwik.dev/core';
import { useSignOut } from '~/routes/plugin@auth';

export default component$(() => {
  const signOut = useSignOut();
  return <button onClick$={() => signOut.submit({ redirectTo: '/signedout' })}>Sign Out</button>;
});
```

## REST API

All the same REST APIs as provided by Auth.js are available.

### signin

**GET /auth/signin**

Displays the built-in/unbranded sign-in page.

**POST /auth/signin/:provider**

Starts a provider-specific sign-in flow. In the case of an OAuth provider, calling this endpoint will initiate the Authorization Request to your Identity Provider.  This endpoint is also used by the [useSignIn](#useSignIn) action internally.

### callback

**GET/POST /auth/callback/:provider**

### signout

**GET /auth/signout**

Displays the built-in/unbranded sign out page.

**POST /auth/signout**

Handles signing the user out - this is a POST submission to prevent malicious links from triggering signing a user out without their consent. The user session will be invalidated/removed from the cookie/database, depending on the flow you chose to store sessions. This endpoint is also used by the [useSignOut](#useSignOut) method internally.

### session

**GET /auth/session**

Returns client-safe session object - or an empty object if there is no session. The contents of the session object that is returned are configurable with the session callback. Session data can also be retrieved using the [useSession](#useSession) routerLoader.

### csrf

**GET /auth/csrf**

Returns object containing CSRF token. In NextAuth.js, CSRF protection is present on all authentication routes. It uses the "double submit cookie method", which uses a signed HttpOnly, host-only cookie. The CSRF token returned by this endpoint must be passed as form variable named csrfToken in all POST submissions to any API endpoint.

### providers

**GET /auth/providers**

Returns a list of configured OAuth services and details (e.g. sign in and callback URLs) for each service. It is useful to dynamically generate custom sign up pages and to check what callback URLs are configured for each OAuth provider that is configured.

## Examples

### GitHub

1. Follow the [GitHub OAuth Guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) to get your `GitHub Client ID`, `GitHub Client Secrets` and generate `AUTH_SECRET` using `openssl rand -base64 32` or [Secret Generator](https://generate-secret.vercel.app/32).
2. Since the default `plugin@auth.ts` uses GitHub as an example, we don't need to change anything there. However a provider other than GitHub could be used or additional provides could be added. Auth.js also supports many [additional options](https://next-auth.js.org/configuration/options#options) that can be set in this file.

```ts title="src/routes/plugin@auth.ts"
import { QwikAuth$ } from "@auth/qwik";
import GitHub from "@auth/qwik/providers/github";

export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
  () => ({
    providers: [GitHub],
  }),
);
```

<Note title="IMPORTANT">Make sure to keep the `onRequest` export as it is used to handle the OAuth flow redirects. Once the user finished OAuth flow, GitHub (or any other provider) will redirect the user back to the application to `/auth/callback/github` (or `/auth/callback/[otherProvider]`). The `onRequest` middleware function will handle requests to this endpoint and finish the OAuth flow.</Note>

3. Create or edit the `.env.local` file at the root of your project to store secrets

```bash title=".env.local"
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
AUTH_SECRET=
```

<Note title="IMPORTANT">Please read the Qwik documentation about [Environment Variables](/docs/guides/env-variables/) to ensure you are using them safely. Many provider secrets should be kept secure and not exposed to the client/browser.</Note>

4. The application is now ready to implement authentication using Auth.js.
5. Enjoy!

### Credentials

<LongNote title="Warning: Credentials Authentication">
This functionality is discouraged by Auth.js.

https://next-auth.js.org/providers/credentials

- The functionality provided for credentials based authentication is intentionally limited to discourage use of passwords due to the inherent security risks associated with them and the additional complexity associated with supporting usernames and passwords.
</LongNote>

1. Since the default `plugin@auth.ts` uses GitHub as an example, we need to replace it with Credentials.

```ts title="src/routes/plugin@auth.ts"
import { QwikAuth$ } from "@auth/qwik";
import Credentials from "@auth/qwik/providers/credentials";

export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
  () => ({
    providers: [
      Credentials({
        async authorize(credentials, req) {
          // Add logic here to look up the user from the credentials supplied
          const user = {
            id: 1,
            name: "Mike",
            email: "mike@example.com",
          };

          return user;
        },
      }),
    ],
  }),
);
```

2. Create or edit the `.env.local` file at the root of your project to store secrets

```bash title=".env.local"
AUTH_SECRET=
```

<Note title="IMPORTANT">Please read the Qwik documentation about [Environment Variables](/docs/guides/env-variables/) to ensure you are using them safely. Many provider secrets should be kept secure and not exposed to the client/browser.</Note>

3. The application is now ready to implement authentication using Auth.js.
4. Enjoy!

### Route Protection

Session data can be accessed via the route `event.sharedMap`.  So a route can be protected and redirect using something like this located in a `layout.tsx` or page `index.tsx`:

```tsx
export const onRequest: RequestHandler = (event) => {
  const session: Session | null = event.sharedMap.get('session');
  if (!session || new Date(session.expires) < new Date()) {
    throw event.redirect(302, `/auth/signin?callbackUrl=${event.url.pathname}`);
  }
};
```

<Note>If placed in a layout.tsx ensure that the redirect destination does not share the same layout.tsx or a redirection loop could occur.</Note>
