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:
- Users are directed to OneGraph
- OneGraph directs the user to the underlying service for authentication, then redirects them back to your site
- 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
Name | Type | Description |
---|---|---|
service | string | One 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_id | string | Your app id (create an app on the Dashboard) |
response_type | string | This value should always be code |
state | string | An unguessable random string that is used to protect against cross-site request forgery |
redirect_origin | string | The URL in your application where users will be sent. This should be listed as one of your CORS origins |
redirect_path | string | Optional 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
Name | Type | Description |
---|---|---|
grant_type | string | This value should be authorization_code |
service | string | One 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_id | string | Your app id |
redirect_uri | string | A combination of the redirect_origin and redirect_path you provided in the previous request |
code | string | The code you received |
expires_in | int | Optional 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
Name | Type | Description |
---|---|---|
grant_type | string | This value should be refresh_token |
app_id | string | The app id that created the token |
refresh_token | string | The refresh token that you received with the original token |
expires_in | int | Optional 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.