• Docs
  • Pricing
  • Support
  • Blog
  • Login

›Intro

Intro

  • What's OneGraph?
  • How does it work?
  • Creating your first app
  • Making your first query
  • OneGraphiQL
  • Authentication & Security Overview
  • Custom Google Auth

On the frontend

  • Using with Apollo
  • Log in to services
  • Example with create-react-app

External Authentication

  • What are JWTs?
  • AuthGuardian
  • Securing your Apollo server
  • Securing your Hasura API
  • Securing your Netlify site
  • Securing your express.js app
  • Advanced JWT customization with webhooks

Subscriptions

  • Subscriptions
  • Webhook-based subscriptions
  • Websocket-based subscriptions
  • Salesforce subscriptions
  • GitHub subscriptions
  • Gmail Subscriptions

Advanced

  • Persisted Queries
  • Mailchimp Signup with Persisted Queries

OneGraph Browser Authentication and Security

This is an overview of how OneGraph's auth flow works. If you're building applications in the browser, you can save yourself some work and use our auth.js library.

OneGraph handles service authentication for your app to make querying against e.g. Twitter or Google on your user's behalf much easier.

There are a few different kinds of authentication OneGraph offers, but we'll focus on in-browser authetication for now.

Let's first query some data to see if "me" (the current user) is logged into Twitter:

{
  me {
    twitter {
      screenName
      name
    }
  }
}

The response comes back:

{
  "data": {
    "me": {
      "twitter": null
    }
  }
}

Check out similar queries for other services OneGraph support, like GitHub, and Stripe!

Asking your user to sign in

With the above me query, now all we need to complete logging into a service like Twitter is to have OneGraph guide them through the OAuth flow.

The flow to authorize users for a service is:

  1. Users are directed to OneGraph
  2. OneGraph directs the user to the underlying service for authentication, then redirects them back to your site
  3. Your app accesses their data with an access token that OneGraph provides

1. Users are directed to OneGraph

GET https://serve.onegraph.com/oauth/start

Query Parameters

NameTypeDescription
servicestringOne of the services that OneGraph supports (eventil, github, gmail, google, google-compute, google-docs, salesforce, stripe, twilio, twitter, youtube, and zendesk as of July 2018)
app_idstringYour app id (create an app on the Dashboard)
response_typestringThis value should always be code
statestringAn unguessable random string that is used to protect against cross-site request forgery
redirect_originstringThe URL in your application where users will be sent. This should be listed as one of your CORS origins
redirect_pathstringOptional param that specifies the path of the url that users will be redirected to

Example url

https://serve.onegraph.com/oauth/start?service=gmail&app_id=${YOUR_APP_ID}&response_type=code&state=s123&redirect_origin=https://example.com&redirect_path=/foo

2. OneGraph redirects users back to your site

If your user gives access, OneGraph will redirect them back to your site with a temporary code in a code parameter, along with the state you provided in a state parameter. Make sure the state param matches the one you provided.

Exchange the code for an access token:

POST https://serve.onegraph.com/oauth/token

Query Parameters

NameTypeDescription
grant_typestringThis value should be authorization_code
servicestringOne of the services that OneGraph supports (eventil, github, gmail, google, google-compute, google-docs, salesforce, stripe, twilio, twitter, youtube, and zendesk as of July 2018)
app_idstringYour app id
redirect_uristringA combination of the redirect_origin and redirect_path you provided in the previous request
codestringThe code you received
expires_inintOptional param that specifies the number of seconds until the token should expire. Use this to help you test the refresh flow. Providing a value that is over two weeks of seconds will cause the request to be rejected. If you need long-lived tokens, go to the Auth Services > Server-side page of the dashboard.

If successful the response will be json-encoded with keys access_token and expires_in, the number of seconds until the token expires. It will also contain a refresh token you can use to generate a new access_token once your current token expires.

Example curl request

curl -X POST https://serve.onegraph.com/oauth/token?grant_type=authorization_code&service=gmail&app_id=$YOUR_APP_ID&redirect_uri=https://example.com/foo&code=c123

Reponse

{
  "access_token": "abcd123",
  "expires_in": 8600,
  "refresh_token": "efgh456"
}

If there is an error, the response will be json-encoded with a short error message under the error key, and a longer description under the error_message key:

{
  "error": "invalid_grant",
  "error_description": "code is expired"
}

Use the access token from the response to make requests to OneGraph using the Authentication header:

Authorization: Bearer YOUR_TOKEN

If the token is "abc123", the request will be:

curl -X POST 'https://serve.onegraph.com/graphql?app_id=0b33e830-7cde-4b90-ad7e-2a39c57c0e11' \
  -H "Authorization: Bearer abc123" \
  --data '{"query":"{ me { twitter { screenName } } }"}'

If you want to log in to multiple services, pass an existing access_token in the Authorization header when you exchange the code for an auth token. The auths for that token will be added to the token that is returned to you.

That's enough to get going! We'll handle security and safety, relying on the OneGraph's handling of the browser's built-in cookie and CORS mechanisms.

You may want to use some of the handy-dandy convenience npm packages that add features and polish (check out the front-end dev section further along), but that's OneGraph browser authentication at its core.

Now if we try the same query above (after logging in), the response looks like:

{
  "data": {
    "me": {
      "twitter": {
        "screenName": "onegraphio",
        "name": "OneGraph"
      }
    }
  }
}

Refreshing a token

Once your access token expires, you can get a new token with the refresh token you received when exchanging the code.

POST https://serve.onegraph.com/oauth/token

Query Parameters

NameTypeDescription
grant_typestringThis value should be refresh_token
app_idstringThe app id that created the token
refresh_tokenstringThe refresh token that you received with the original token
expires_inintOptional param that specifies the number of seconds until the token should expire. Use this to help you test the refresh flow. Providing a value that is over two weeks of seconds will cause the request to be rejected. If you need long-lived tokens, go to the Auth Services > Server-side page of the dashboard.

Example request

curl -X POST https://serve.onegraph.com/oauth/token?grant_type=refresh_token&app_id=${YOUR_APP_ID}&refresh_token=efgh456

Reponse

{
  "access_token": "ijkl789",
  "expires_in": 8600,
  "refresh_token": "mnop012"
}

You will get a new access_token and a new refresh_token. You can discard the refresh_token that you used and replace it with the refresh_token in the response.

Browser security

OneGraph strictly enforces a safe-list of CORS origins for your app. No request originating from an app outside of your safe list will have access to any of the service authentications your user has given your app.

Go check out your app in the OneGraph dashboard now and add http://localhost:3000 to the list of CORS origins allowed to get started building an app locally.

What's next?

Take a look at how to use OneGraph with your existing Apollo or Relay clients to get started, explore your queries in OneGraphiQL or get live help on our Spectrum channel for any questions and suggestions.

← OneGraphiQLCustom Google Auth →
Links
OneGraph Overview Example projectsOneGraphiQL Explorer
Support
Live chat on Spectrum> TwitterBlog
More
Terms of ServicePrivacy Policy
Copyright © 2021 OneGraph