Skip to content

Latest commit

 

History

History
34 lines (30 loc) · 3.36 KB

how-it-works.md

File metadata and controls

34 lines (30 loc) · 3.36 KB
Raw

How It Works

⚠️ Headless authentication can be confusing. Before you continue, please review some common terminology.

As follows is a brief overview of how the plugin works.

  1. Visit your WordPress site's admin Dashboard > GraphQL > Settings > Headless Login, and enable/configure the authentication providers you want to use and any other plugin settings.
  2. In your frontend app, pass the required data to the login (or linkUserIdentity) mutation to authenticate a user.
  • For Email/Password: Pass the user's email and password to the LoginInput.credentials input arg.
  • For OAuth Providers:
    1. Get the Client authorizationUrl from the RootQuery.loginClients field in GraphQL to use in your client app (or DIY with a frontend dependency like Auth.js).
    2. When your frontend user clicks and visits the authorizationUrl, they'll be propmpted to login with the provider. If authorization is successful, they (along with the Authorization response ) will be redirected to the redirectUri you configured in the Provider's settings.
    3. The Provider's authorization response should then be passed via the LoginInput.oauthResponse input arg.
  • For Site Token:
    1. Set the special token you set on the request header you configured in the Provider settings.
    2. Pass the user_identity of the user you want to authenticate to the LoginInput.identity input arg. This could be a username, email, or resource owner ID from a frontend dependency like Auth.js. Note: Whenever possible, the mutations should be called from a server-side environment (like Next.js API route or AWS Lambda) to avoid exposing authentication and authroization credentials to the public.
  1. Your WordPress server will then:
    • Validate the authentication response.
    • Fetch the Resource Owner's profile data from the provider.
    • (optional) Create a new WordPress user and/or link an existing WordPress user to the Provider's Resource Owner.
    • Generate and returns a JWT authToken and refreshToken for the user to use in future requests.
  2. Your frontend app should and and store the authToken and refreshToken in a secure location (like a Web Worker or secure cookie) for future requests.
  • Authentication tokens should be passed in the Authorization Headers of future GraphQL requests.
  • Refresh tokens can be exchanged for a new auth token without requiring the user to reauthenticate.
  • Woocommerce - If you're using WPGraphQL for WooCommerce, you should store and pass the wooSessionToken to the woocommerce-session header.
  1. You can get a new authToken and refreshToken for the user in the response of an authenticated query by querying for the RootQuery.viewer.auth.authToken, or exchanged a stored refreshToken for a new authToken using the refreshToken mutation.
  2. You can log the user out of all other devices by using refreshUserSecret or revokeUserSecret mutations.

Next Steps