GeoOP

Client Information

All clients that have not been certified by GeoOp are assumed to be of public type.

Authentication Process

Since full authentication of client is not required (it does not store client secret) it can choose between the following two grant types:

• Authorisation Code Grant – recommended if client wants to make a background call to obtain an access token
• Implicit Code Grant – recommended when client does not want to make additional requests to obtain an access token (note that the access token may get exposed in this case)

Authorisation Code Grant

The Third-Party Application is required to redirect resource owner to the GeoOp login page. Once authenticated by GeoOp, the resource owner then authorises the Third-Party Application to act on their behalf and grants it certain permissions (up to the limit allowed by the developer).

1. The application shows a welcome screen and asks the resource owner to sign in via the GeoOp website:
   

2. The application launches a web browser (either embedded or an external browser application) and redirects the resource owner to the login page. It includes its client ID into the request URL and states the desired response type (must be code). It also provides a scope parameter (must be default). Optionally, it can include a state parameter and assign it any value:

   GET /oauth2/code?response_type=code&client_id=s6BhdRkqt3&scope=default&state=xyz HTTP/1.1
   Host: login.geoop.com

3. The Authentication Server generates a login page and asks the resource owner to enter their credentials:
   

4. The resource owner enters their credentials and clicks the 'Sign In' button.

5. The Authentication Server authenticates the resource owner and loads information about the client based on the provided client ID.

6. It then generates a page where the resource owner is presented with some basic information about the client and is asked to authorise the application to act on their behalf:
   
   Note that the resource owner may not be allowed to select which permissions to grant to the client if that option has been disabled by the client developer.

7. The resource owner submits the form and the Authentication Server generates a short-lived authorisation code and links the selected permissions, the resource owner ID and the client ID to it.

8. Finally, the Authentication Server instructs the browser to redirect the resource owner back to the Third-Party Application via the registered redirect URI and adds the authorisation code to that URI. If the state parameter has been received in step 2, then its sanitised value is also added to the URI:

   HTTP/1.1 302 Found
   Location: application://oauth?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

9. The Third-Party Application shows a confirmation screen to the resource owner:
   

10. At the same time it makes a background request to the Authentication Server and provides it with its credentials and the authentication code:

    POST /oauth2/token HTTP/1.1
    Host: login.geoop.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=s6BhdRkqt3

11. The Authentication Server authenticates the client (Third-Party Application) and loads the permissions and resource owner ID linked to the authorisation code.

12. It then generates an access token and links the permissions and resource owner ID to that token.

13. Finally, it returns the following response to the client (note that public clients are not allowed to request or receive refresh token):

    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Cache-Control: no-store
    Pragma: no-cache
    
    {
    

     

    "access_token":"oJ_7Hj.f-F3f.kL",
    

     

    "token_type":"Bearer",
    

     

    "expires_in":3600
    }

14. The Third-Party Application stores the access token and can now make direct API calls.

15. It uses the data retrieved from the API Server to generate the application interface:
    

Implicit Code Grant

The process is quite similar to the one described above, although it involves less steps, but is also less secure (as the access token may get exposed, for example, in the address bar of a browser).

1. The application shows a welcome screen and asks the resource owner to sign in via the GeoOp website:
   

2. The application launches a web browser (either embedded or an external browser application) and redirects the resource owner to the login page. It includes its client ID into the request URL and states the desired response type (must be token). It also provides a scope parameter (must be default). Optionally, it can include a state parameter and assign it any value:

   GET /oauth2/token?response_type=token&client_id=s6BhdRkqt3&scope=default&state=xyz HTTP/1.1
   Host: login.geoop.com

3. The Authentication Server generates a login page and asks the resource owner to enter their credentials:
   

4. The resource owner enters their credentials and clicks the 'Sign In' button.

5. The Authentication Server authenticates the resource owner and loads information about the client based on the provided client ID.

6. It then generates a page where the resource owner is provided with some basic information about the client and is asked to authorise the application to act on their behalf:
   
   Note that the resource owner may not be allowed to select which permissions to grant to the client if that option has been disabled by the client developer.

7. The resource owner submits the form and the Authentication Server generates an access token and links the permissions and resource owner ID to that token.

8. Finally, the Authentication Server instructs the browser to redirect the resource owner back to the Third-Party Application via the registered redirect URI and adds the access token to that URI. If the state parameter has been received in step 2, then its sanitised value is also added to the URI:

   HTTP/1.1 302 Found
   Location: application://oauth?token=oJ_7Hj.f-F3f.kL&token_type=Bearer&expires_in=3600&state=xyz

9. The Third-Party Application stores the access token and can now make direct API calls.

10. It uses the data retrieved from the API Server to generate the application interface:
    

On Access Token Expiration

Since public Third-Party Application cannot receive refresh token, when the access token expires it has to obtain a new access token from the Authentication Server by following either of the above described procedures.

Making API Requests

Once the application has obtained the access token, it can make API calls to the GeoOP API Server. It must use the Authorization request header as in the example below: