In the Geodrop world some concepts will be named by their Geodrop's name instead of OAuth2's.
Thus, instead of "Resource Owner", "Client" and "Authorization/Resource Server", we'll talk about "User", "Application" and "Authorization/API Server".
Other concepts, will keep their OAuth2's name, i.e., "Authorization Endpoint", "Token Endpoint" and "User-Agent".
OAuth2 employs four different mechanisms, called "flows", to authenticate and authorize clients, however only three of them are meaningful for the Geodrop System (i.e. Authorization Code, Implicit and Resource Owner Password Credentials).
These are the entities involved in the OAuth2 flows:
| Definition |
Description |
|
User
|
is the User's web-browser used to access the Application.
|
|
Client
|
native applications (Resource Owner Password Credentials flow) have their own interface the User can access directly, without the aid of a web-browser.
|
|
Application
|
if native, it is accessed through the device it is running on. If user-agent-based (e.g., JavaScript), it is downloaded from some public URL and executed in the User-Agent. If web application, it is accessed through some public URL and executed on a third-party server.
|
|
AuthorizationEndpoint
|
is a public URL to access the login page of the Authorization server.
|
|
ResourceServer
|
is another role played by the API Gateway, where it is acting as a proxy for the API or other components of the Geodrop System.
|
| Not all of them are involved in all the flows. |
The flows described in this document, were adapted to the Geodrop System. For a description of the original OAuth2 flows, see OAuth 2.
The diagram below summarize the OAuth Authorization Code protocol in order to access to a specific resource.
The Geodrop Endpoints for this scenario are:
- The user access an application in order to use a Geodrop resource
-
The application redirect the user client to a login page on the Geodrop authentication server,
the user inserts his data and if succeded, then the user client is redirect to a previously given URL
with a parameter code that contains the authorization grant necessary for request the access token
- The application call the Geodrop authorization server in order to obtain the access token
- The authorization server returns the pair
<access-token, refresh-token>
- Now the application can call the resource requested by the user
List of Endpoints for this protocol flow
| Endpoint |
URI |
Params |
| Authorization |
https://geodrop.com/oauth |
| Name |
Mandatory |
Note |
| response_type |
yes |
Fixed value: code |
| client_id |
yes |
|
| redirect_uri |
no |
if not specified will be used the app default URI |
| scope |
no |
At the moment all values will be ignored |
| state |
no |
|
|
| Access |
https://api.geodrop.net/tokenrequest
Note: basic authentication with client_id/client_secret needed |
| Name |
Mandatory |
Note |
| grant_type |
yes |
Fixed value: authorization_code |
| code |
yes |
the authorization code previously obtained |
| client_id |
no |
if present must match the value expressed in the basic authentication header |
| redirect_uri |
no |
if not specified will be used the app default URI |
| scope |
no |
At the moment all values will be ignored |
|
| Refresh |
https:/api.geodrop.net/tokenrequest
Note: basic authentication with client_id/client_secret needed |
| Name |
Mandatory |
Note |
| grant_type |
yes |
Fixed value: refresh_token |
| client_id |
no |
if present must match the value expressed in the basic authentication header |
| refresh_token |
yes |
refresh-token previously obtained with a access-token |
| redirect_uri |
no |
if not specified will be used the app default URI |
| scope |
no |
At the moment all values will be ignored |
|
Here is a JSON example of an access token response:
{"access_token":"<32-hexadecimal-digits>",
"token_type":"bearer",
"expire_in":"< unix-timestamp >",
"refresh_token":"<32-hexadecimal-digits>"}
This flow is optimized for Application implemented as JavaScript code to be executed in the User's client.
The figure below shows how it works.
- The user access an application in order to use a Geodrop resource
-
The application redirect the user client to a login page on the Geodrop authentication server,
the user inserts his data and if succeded, then the user client is redirect to a previously given URL
with a parameter access-token that contains the access token necessary for call API
- Now the application can call the resource requested by the user
| Endpoint |
URI |
Params |
| Authorization |
https://geodrop.com/oauth
Note: basic authentication with client_id/client_secret needed |
List of Endpoints for this protocol flow
| Name |
Mandatory |
Note |
| response_type |
yes |
Fixed value: token |
| client_id |
yes |
|
| redirect_uri |
no |
if not specified will be used the app default URI |
| scope |
no |
At the moment all values will be ignored |
|
Here is an example of an access token response given as fragment URL:
< redirect_URI>#access_token=<32-hexadecimal-digits>&token_type=bearer&expire_in=< unix-timestamp >
This flow is optimized for application implemented as native application running on some device (cell-phone, PC, etc.).
The figure shows how it works:
- The user access an application in order to use a Geodrop resource
-
The application request an access token to the Geodrop authentication server, if succeded,
then the API will return to a previously given URL with the pair <access-token, refresh-token>
that contains the access token necessary for call API
- Now the application can call the resource requested by the user
| Endpoint |
URI |
Params |
| Authorization |
https://api.geodrop.net/tokenrequest
Note: basic authentication with client_id/client_secret needed |
List of Endpoints for this protocol flow
| Name |
Mandatory |
Note |
| grant_type |
yes |
Fixed value: password |
| username |
yes |
|
| password |
yes |
user password |
| client_id |
no |
if present must match the value expressed in the basic authentication header |
| redirect_uri |
no |
if not specified will be used the app default URI |
| scope |
no |
At the moment all values will be ignored |
|
| Refresh |
https://api.geodrop.net/tokenrequest
Note: basic authentication with client_id/client_secret needed |
| Name |
Mandatory |
Note |
| grant_type |
yes |
Fixed value: refresh_token |
| client_id |
no |
if present must match the value expressed in the basic authentication header |
| refresh_token |
yes |
refresh-token previously obtained with a access-token |
| redirect_uri |
no |
if not specified will be used the app default URI |
| scope |
no |
at the moment all values will be ignored |
|
Here is a JSON example of an access token response:
{"access_token":"<32-hexadecimal-digits>",
"token_type":"bearer",
"expire_in":"< unix-timestamp >",
"refresh_token":"<32-hexadecimal-digits>"}
