OAuth
data.world supports the OAuth 2.0 protocol for authentication and authorization.
If you are new to OAuth 2.0, the OAuth 2.0 Guide is a good place to start and learn some of the theory.
Following is an example of what the user experience might look like in your product:
Auth Steps
All applications follow a basic pattern when accessing a data.world API using OAuth 2.0. The flow can be slightly different, depending on whether the application web-based or native (desktop & mobile).
Web Application Flow
- Application redirects user to
https://auth.data.world/oauth/authorize
for authorization, providing the following parameters:client_id
redirect_uri
response_type = "code"
state
Example Authorization URL:
https://auth.data.world/oauth/authorize?
client_id=3MVG9lKcPoNINVB&
redirect_uri=http://localhost/oauth/code_callback&
response_type=code
-
User logs into data.world and grants application access.
-
data.world redirects user back to the
redirect_uri
with:code
state
-
Application takes the
code
and exchanges it for an access token:client_id
client_secret
code
redirect_uri
(optional)grant_type = "authorization_code"
Example Token Request:
https://data.world/oauth/access_token?
code=zac4ZV2XbleQ2e&
client_id=3MVG9lKcPoNINVB&
client_secret=3iQF9BsWEr6nCf&
grant_type=authorization_code
- If
client_id
andclient_secret
are valid data.world will respond with:access_token
expires_in
refresh_token
Alternatively, if a redirect_uri
was provided, data.world
will invoke it passing the same list of attributes.
- Application stores
access_token
to use in subsequent requests by placing it into the request as anAuthorization: Bearer [access_token]
header string.
This flow requires that your application runs on a web server
- Steps #3 and #4 can be performed while your
client_secret
remains protected behind a server environment.- DO NOT include your
client_secret
for your web app in source code that accessible to others.- Use the native applications flow instead, if you cannot guarantee the confidentiality of your
client_secret
.
Native Application Flow (desktop, mobile and static apps)
data.world supports the Proof Key for Code Exchange protocol to make the native application flow more secure.
A unique code verifier is created for every authorization request, and its transformed value, called code_challenge
, is sent to the authorization server to obtain the authorization code.
Create the code verifier
A codeverifier is a high-entropy cryptographic random string using the unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "" / "~"`, with a minimum length of 43 characters and a maximum length of 128 characters.
The code verifier should have enough entropy to make it impractical to guess the value.
Create the code challenge
Two methods of creating the code challenge are supported.
plain
: The code challenge is the same value as the code verifier generated above (code_challenge = code_verifier
).S256
: The code challenge is the Base64URL (with no padding) encoded SHA256 hash of the code verifier (code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
).
Once the values for code_verifier
, code_challenge
and code_challenge_method
are defined, the flow proceeds, as follows:
- Application redirects user to
https://auth.data.world/oauth/authorize
for authorization, providing the following parameters:client_id
redirect_uri
response_type = "code"
state
code_challenge_method = "S256" or "plain"
code_challenge
Example Authorization URL:
https://auth.data.world/oauth/authorize?
client_id=3MVG9lKcPoNINVB&
redirect_uri=http://localhost/oauth/code_callback&
response_type=code&
code_challenge_method=plain&
code_challenge=kBPZPENCUAfHyZRoGicqwhuzDawVgtpLsUpfJEvQgGbg6iEHqiteoDjrtgaErwEJ
-
User logs into data.world and grants application access.
-
data.world redirects user back to the
redirect_uri
with:code
state
-
Application takes the
code
and exchanges it for an access token:client_id
client_secret
code
redirect_uri
(optional)grant_type = "authorization_code"
code_verifier
Example Token Request:
https://auth.data.world/oauth/access_token?
code=zac4ZV2XbleQ2e&
client_id=3MVG9lKcPoNINVB&
client_secret=3iQF9BsWEr6nCf&
grant_type=authorization_code&
code_verifier=kBPZPENCUAfHyZRoGicqwhuzDawVgtpLsUpfJEvQgGbg6iEHqiteoDjrtgaErwEJ
- If
client_id
andclient_secret
are valid data.world will respond with:access_token
expires_in
refresh_token
Alternatively, if a redirect_uri
was provided, data.world
will invoke it passing the same list of attributes.
- Application stores
access_token
to use in subsequent requests by placing it into the request as anAuthorization: Bearer [access_token]
header string.
Reference implementation
Check out our reference implementation on GitHub.
This example, written in Node.js can be deployed to your Heroku account as-is with click of a button. Super easy!
Look for the Deploy to Heroku button at the bottom of the README.md.
Updated 8 months ago