{"id":222,"date":"2021-06-28T05:32:39","date_gmt":"2021-06-28T11:32:39","guid":{"rendered":"https:\/\/developers.wpengine.com\/blog\/?p=222"},"modified":"2026-02-05T21:00:26","modified_gmt":"2026-02-06T03:00:26","slug":"headless-wordpress-authentication-native-cookies","status":"publish","type":"post","link":"https:\/\/wpengine.com\/builders\/headless-wordpress-authentication-native-cookies\/","title":{"rendered":"Headless WordPress Authentication with Native Cookies"},"content":{"rendered":"\n

When developing a traditional, monolithic WordPress site, you typically don’t give authentication a second thought. WordPress already provides a native cookie-based authentication system that works out of the box.<\/p>\n\n\n\n

What you may not<\/em> know is that for a headless WordPress project, it’s possible to leverage that same authentication system in your decoupled JavaScript frontend app!<\/p>\n\n\n\n

In this post, we’ll explore a Next.js app<\/a> that uses WordPress’ own native authentication cookies to provide the following functionality:<\/p>\n\n\n\n

  1. Log in<\/li>
  2. Log out<\/li>
  3. New user sign-ups<\/li>
  4. Password resets<\/li>
  5. User profile page<\/li>
  6. A “Members” page with gated content that only authenticated users can access<\/li>
  7. A “Create Post” page where users with the publish_posts<\/code> capability can create new posts, but other users can’t.<\/li>
  8. A useAuth()<\/code> custom hook that provides the user’s loggedIn<\/code> status and user details to the rest of the app via React context.<\/li>
  9. Helper components to limit certain content to only authenticated\/unauthenticated users.<\/li><\/ol>\n\n\n\n

    (A Gatsby.js<\/a> port of the codebase also exists, here<\/a>)<\/p>\n\n\n\n

    To accomplish this, we’ll leverage the WPGraphQL CORS<\/a> plugin, which allows us to tell WordPress to not only accept cookies from the domain where WP is installed, but also from the decoupled frontend app’s domain. That way, the same cookies can be used to authenticate users on both domains.<\/p>\n\n\n\n

    Getting Started<\/h2>\n\n\n\n

    To benefit from this post, you should be familiar with the basics of local WordPress<\/a> development, WPGraphQL<\/a>, React<\/a>, and Apollo Client<\/a>.<\/p>\n\n\n\n

    Here are the steps for getting set up:<\/p>\n\n\n\n

    WordPress Backend Setup<\/h3>\n\n\n\n
    1. Set up a local WordPress site and get it running.<\/li>
    2. Install and activate the WPGraphQL<\/a>, WPGraphQL CORS<\/a>, and Headless WordPress Email Settings<\/a> WordPress plugins.<\/li>
    3. From the WordPress admin sidebar, go to GraphQL<\/code> > Settings<\/code> and click the CORS Settings<\/code> tab.<\/li>
    4. Check the checkboxes next to these options:
      – Send site credentials<\/code>
      – Enable login mutation<\/code>
      – Enable logout mutation<\/code><\/li>
    5. In the Extend \"Access-Control-Allow-Origin\u201d header<\/code> field, enter http:\/\/localhost:3000<\/code> and click the button to save your changes.<\/li><\/ol>\n\n\n\n

      The CORS Settings page should now look like this:<\/p>\n\n\n\n

      \"Screenshot<\/figure>\n\n\n\n

      Next.js App Setup<\/h3>\n\n\n\n
      1. Clone down the Next.js app<\/a> repo.<\/li>
      2. Create a .env.local<\/code> file inside of the app’s root folder. Open that file in a text editor and paste in NEXT_PUBLIC_WORDPRESS_API_URL=https:\/\/headlesswpcookieauth.local\/graphql<\/code>, replacing headlesswpcookieauth.local<\/code> with the domain for your local WordPress site. This is the endpoint that Apollo Client will use when it sends requests to your WordPress backend.<\/li>
      3. Run npm install<\/code> (or yarn<\/code>) to install the app’s NPM dependencies.<\/li>
      4. Run npm run dev<\/code> to get the server running locally.<\/li>
      5. You should now be able to visit http:\/\/localhost:3000\/<\/a> in a web browser and see the app’s homepage.<\/li><\/ol>\n\n\n\n

        Alternatively, you can follow the steps for getting set up with the Gatsby.js port of this codebase<\/a>.<\/p>\n\n\n\n

        Try it Out!<\/h2>\n\n\n\n

        Take a minute to explore the app. Try logging in and logging out. You’ll notice that the top navigation bar re-renders to show different things when you’re logged in vs. logged out, and that some pages are only accessible when you’re logged in\/out.<\/p>\n\n\n\n

        How it Works<\/h2>\n\n\n\n

        At a high level, our authentication system works like this:<\/p>\n\n\n\n

        1. An unauthenticated user navigates to the Log In page and attempts to log in.<\/li>
        2. Our app fires off a GraphQL request to the WordPress backend with that user’s email address and password.<\/li>
        3. If the credentials are valid, WordPress sends an HttpOnly cookie<\/a> back to the client, along with a success response.<\/li>
        4. Knowing that the user has been logged in successfully, our app is then able to fire off a request to get some basic info about that user and re-render the app to display links and pages meant for authenticated users.<\/li>
        5. Requests made to the WordPress backend after that point include the auth cookie in the request headers, which is used to authenticate the user.<\/li><\/ol>\n\n\n\n

          A Note on Security<\/h3>\n\n\n\n

          That “HttpOnly” cookie part is important. Some other authentication strategies involve storing an authentication token in local storage<\/a> or in a cookie that does not have the HttpOnly<\/code> attribute. That means that the site would be vulnerable to a cross-site scripting<\/a> (XSS) attack where some rogue client-side JavaScript code would be able to “reach” into local storage\/the non-HttpOnly cookie to get the auth token, then make authenticated requests on behalf of the user without their permission. More info on that type of vulnerability can be found here<\/a>.<\/p>\n\n\n\n

          Since our cookie does<\/em> have the HttpOnly<\/code> attribute, it is not accessible at all via client-side JavaScript, and therefore not vulnerable to the type of cross-site scripting (XSS) attack mentioned above. This results in more robust security.<\/p>\n\n\n\n

          Apollo Client Configuration<\/h3>\n\n\n\n

          Apollo Client is initialized in lib\/apolloClient.ts<\/code>.<\/p>\n\n\n

          import<\/span> { ApolloClient, InMemoryCache, createHttpLink } from<\/span> \"@apollo\/client\"<\/span>;\n<\/span><\/span>\n<\/span><\/span>const<\/span> link = createHttpLink({\n<\/span><\/span>  uri<\/span>: process.env.NEXT_PUBLIC_WORDPRESS_API_URL,\n<\/span><\/span>  credentials<\/span>: 'include'<\/span>,\n<\/span><\/span>});\n<\/span><\/span>\n<\/span><\/span>export<\/span> const<\/span> client = new<\/span> ApolloClient({\n<\/span><\/span>  cache<\/span>: new<\/span> InMemoryCache(),\n<\/span><\/span>  link\n<\/span><\/span>});\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          The credentials: 'include',<\/code> option is what tells Apollo to send the auth cookie along with every request.<\/p>\n\n\n\n
          The client<\/code> from that file is then passed as a prop into the ApolloProvider<\/code> component in pages\/_app.tsx<\/code>, which allows us to make GraphQL network requests from anywhere in our app.<\/p>\n\n\n\n
          useAuth()<\/code> Hook<\/h3>\n\n\n\n
          Take a look at hooks\/useAuth.tsx<\/code>.<\/p>\n\n\n
          const<\/span> AuthContext = createContext(DEFAULT_STATE);\n<\/span><\/span>\n<\/span><\/span>export<\/span> const<\/span> GET_USER = gql`<\/span>\n<\/span><\/span>  query getUser {<\/span>\n<\/span><\/span>    viewer {<\/span>\n<\/span><\/span>      id<\/span>\n<\/span><\/span>      databaseId<\/span>\n<\/span><\/span>      firstName<\/span>\n<\/span><\/span>      lastName<\/span>\n<\/span><\/span>      email<\/span>\n<\/span><\/span>      capabilities<\/span>\n<\/span><\/span>    }<\/span>\n<\/span><\/span>  }<\/span>\n<\/span><\/span>`<\/span>;\n<\/span><\/span>\n<\/span><\/span>export<\/span> function<\/span> AuthProvider<\/span>({ children }: { children: ReactNode }<\/span>) <\/span>{\n<\/span><\/span>  const<\/span> { data, loading, error } = useQuery(GET_USER);\n<\/span><\/span>  const<\/span> user = data?.viewer;\n<\/span><\/span>  const<\/span> loggedIn = Boolean<\/span>(user);\n<\/span><\/span>\n<\/span><\/span>  const<\/span> value = {\n<\/span><\/span>    loggedIn,\n<\/span><\/span>    user,\n<\/span><\/span>    loading,\n<\/span><\/span>    error,\n<\/span><\/span>  };\n<\/span><\/span>\n<\/span><\/span>  return<\/span> <AuthContext.Provider<\/span> value<\/span>={value}<\/span>><\/span>{children}<\/AuthContext.Provider<\/span>><\/span><\/span>\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span>const<\/span> useAuth = ()<\/span> =><\/span> useContext(AuthContext);\n<\/span><\/span>\n<\/span><\/span>export<\/span> default<\/span> useAuth;\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          AuthContent & UnAuthContent Components<\/h3>\n\n\n\n
          These two components are used to conditionally render parts of our application that should only be shown to authenticated or unauthenticated users. They also redirect users who don’t meet that criterion to the proper page.<\/p>\n\n\n\n
          AuthContent<\/h4>\n\n\n\n
          Open up components\/AuthContent.tsx<\/code> to see how this component works.<\/p>\n\n\n
          export<\/span> default<\/span> function<\/span> AuthContent<\/span>({ children }: { children: ReactNode }<\/span>) <\/span>{\n<\/span><\/span>  const<\/span> { loggedIn, loading } = useAuth();\n<\/span><\/span>  const<\/span> router = useRouter();\n<\/span><\/span>\n<\/span><\/span>  \/\/ Navigate unauthenticated users to Log In page.<\/span>\n<\/span><\/span>  useEffect(()<\/span> =><\/span> {\n<\/span><\/span>    if<\/span> (!loading && !loggedIn) {\n<\/span><\/span>      router.push('\/log-in'<\/span>);\n<\/span><\/span>    }\n<\/span><\/span>  }, [loggedIn, loading, router]);\n<\/span><\/span>\n<\/span><\/span>  if<\/span> (loggedIn) {\n<\/span><\/span>    return<\/span> <><\/span>{children}<\/><\/span><\/span>;\n<\/span><\/span>  }\n<\/span><\/span>\n<\/span><\/span>  return<\/span> <p<\/span>><\/span>Loading...<\/p<\/span>><\/span><\/span>;\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          The logic works like this:<\/p>\n\n\n\n
          When our app first boots up, the GET_USER<\/code> query defined here is fired off to see if the user is authenticated. If they are, loggedIn<\/code> is toggled to true<\/code>. It, along with the user<\/code> data and loading<\/code> and error<\/code> states are passed down to the rest of our app via React context<\/a>. This way, any component or hook in our app can use the useAuth()<\/code> hook to access that authentication-related data.<\/p>\n\n\n\n