web/versioned_docs/version-0.15/auth/social-auth/github.md
import useBaseUrl from '@docusaurus/useBaseUrl'; import DefaultBehaviour from './_default-behaviour.md'; import OverrideIntro from './_override-intro.md'; import OverrideExampleIntro from './_override-example-intro.md'; import UsingAuthNote from './_using-auth-note.md'; import WaspFileStructureNote from './_wasp-file-structure-note.md'; import GetUserFieldsType from './_getuserfields-type.md'; import ApiReferenceIntro from './_api-reference-intro.md'; import UserSignupFieldsExplainer from '../_user-signup-fields-explainer.md'; import GithubData from '../entities/_github-data.md'; import AccessingUserDataNote from '../_accessing-user-data-note.md';
Wasp supports Github Authentication out of the box. GitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account.
Letting your users log in using their GitHub accounts turns the signup process into a breeze.
Let's walk through enabling Github Authentication, explain some of the default settings, and show how to override them.
Enabling GitHub Authentication comes down to a series of steps:
User entity.Let's start by properly configuring the Auth object:
<Tabs groupId="js-ts"> <TabItem value="js" label="JavaScript"> ```wasp title="main.wasp" app myApp { wasp: { version: "^0.15.0" }, title: "My App", auth: { // highlight-next-line // 1. Specify the User entity (we'll define it next) // highlight-next-line userEntity: User, methods: { // highlight-next-line // 2. Enable Github Auth // highlight-next-line gitHub: {} }, onAuthFailedRedirectTo: "/login" }, } ``` </TabItem> <TabItem value="ts" label="TypeScript"> ```wasp title="main.wasp" app myApp { wasp: { version: "^0.15.0" }, title: "My App", auth: { // highlight-next-line // 1. Specify the User entity (we'll define it next) // highlight-next-line userEntity: User, methods: { // highlight-next-line // 2. Enable Github Auth // highlight-next-line gitHub: {} }, onAuthFailedRedirectTo: "/login" }, } ``` </TabItem> </Tabs>Let's now define the app.auth.userEntity entity in the schema.prisma file:
To use GitHub as an authentication method, you'll first need to create a GitHub OAuth App and provide Wasp with your client key and secret. Here's how you do it:
http://localhost:3001/auth/github/callback.https://your-server-url.com/auth/github/callback.Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
Let's define the necessary authentication Routes and Pages.
Add the following code to your main.wasp file:
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth.jsx"
}
```
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth.tsx"
}
```
We'll define the React components for these pages in the src/pages/auth.{jsx,tsx} file below.
:::info We are using Tailwind CSS to style the pages. Read more about how to add it here. :::
Let's create a auth.{jsx,tsx} file in the src/pages folder and add the following to it:
export function Login() {
return (
<Layout>
<LoginForm />
</Layout>
)
}
// A layout component to center the content
export function Layout({ children }) {
return (
<div className="h-full w-full bg-white">
<div className="flex min-h-[75vh] min-w-full items-center justify-center">
<div className="h-full w-full max-w-sm bg-white p-5">
<div>{children}</div>
</div>
</div>
</div>
)
}
```
export function Login() {
return (
<Layout>
<LoginForm />
</Layout>
)
}
// A layout component to center the content
export function Layout({ children }: { children: React.ReactNode }) {
return (
<div className="h-full w-full bg-white">
<div className="flex min-h-[75vh] min-w-full items-center justify-center">
<div className="h-full w-full max-w-sm bg-white p-5">
<div>{children}</div>
</div>
</div>
</div>
)
}
```
We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.
Yay, we've successfully set up Github Auth! 🎉
Running wasp db migrate-dev and wasp start should now give you a working app with authentication.
To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.
Add gitHub: {} to the auth.methods dictionary to use it with default settings.
We are using GitHub's API and its /user and /user/emails endpoints to get the user data.
:::info We combine the data from the two endpoints
You'll find the emails in the emails property in the object that you receive in userSignupFields.
This is because we combine the data from the /user and /user/emails endpoints if the user or user:email scope is requested.
:::
The data we receive from GitHub on the /user endpoint looks something this:
{
"login": "octocat",
"id": 1,
"name": "monalisa octocat",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": ""
// ...
}
And the data from the /user/emails endpoint looks something like this:
[
{
"email": "[email protected]",
"verified": true,
"primary": true,
"visibility": "public"
}
]
The fields you receive will depend on the scopes you requested. By default we don't specify any scopes. If you want to get the emails, you need to specify the user or user:email scope in the configFn function.
```prisma title="schema.prisma"
model User {
id Int @id @default(autoincrement())
username String @unique
displayName String
}
// ...
```
```js title="src/auth/github.js"
export const userSignupFields = {
username: () => 'hardcoded-username',
displayName: (data) => data.profile.name,
}
export function getConfig() {
return {
scopes: ['user'],
}
}
```
```prisma title="schema.prisma"
model User {
id Int @id @default(autoincrement())
username String @unique
displayName String
}
// ...
```
```ts title="src/auth/github.ts"
import { defineUserSignupFields } from 'wasp/server/auth'
export const userSignupFields = defineUserSignupFields({
username: () => 'hardcoded-username',
displayName: (data: any) => data.profile.name,
})
export function getConfig() {
return {
scopes: ['user'],
}
}
```
<GetUserFieldsType />
When you receive the user object on the client or the server, you'll be able to access the user's GitHub ID like this:
The gitHub dict has the following properties:
configFn: ExtImportThis function should return an object with the scopes for the OAuth provider.
<Tabs groupId="js-ts"> <TabItem value="js" label="JavaScript"> ```js title="src/auth/github.js" export function getConfig() { return { scopes: [], } } ``` </TabItem> <TabItem value="ts" label="TypeScript"> ```ts title="src/auth/github.ts" export function getConfig() { return { scopes: [], } } ``` </TabItem> </Tabs>userSignupFields: ExtImportRead more about the userSignupFields function here.