GeoOP

Client Information

The Third-Party Server must be able to store its client secret securely. Since GeoOp does not control how that storage is implemented, it is required that any third-party willing for their server client to be assigned the confidential type must first apply for a certificate from GeoOp. The certification procedure allows GeoOp to assess whether the Third-Party Server meets its security standards.

For this article it is assumed that the Third-Party Server has successfully passed the certification procedure.

Authentication Process

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

Initial Authentication

1. The resource owner opens a third-party web page in their browser. The page is generated by the Third-Party Server:
   

2. The Third-Party Server redirects the resource owner to the GeoOp Authentication Server. 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 Server via the registered redirect URI (which must use the HTTPS protocol) 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: https://example.com/demo/oauth?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

9. The Third-Party Server generates a confirmation page and shows it 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&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

    OR (if the server prefers to use the Authorization header):

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

11. The Authentication Server authenticates the client (Third-Party Server) 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 (the refresh token may be omitted if it was not requested by the client in step 2 or if the resource owner opted for forced re-authentication of the client in step 6):

    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,
    

     

    "refresh_token":"52hKUVsnDoy729Hdhi7ff"
    }

14. The Third-Party Server stores securely the access token and the refresh token (if there is any) and can now make direct API calls.

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

On Access Token Expiration

If the Third-Party Server has NOT received a refresh token, then when the access token expires it has to obtain a new access token from the Authentication Server by following the above described procedure.

If the Third-Party Server has received the refresh token, then it can exchange that token for a new access token without having to ask the resource owner to re-authenticate it.

1. The client makes a background request to the Authentication Server in the following format:

   POST /oauth2/token HTTP/1.1
   Host: login.geoop.com
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

   OR (if the server prefers to use the Authorization header):

   POST /oauth2/token HTTP/1.1
   Host: login.geoop.com
   Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

2. The Authentication Server authenticates the client.

3. It loads the permission set linked to the provided refresh token.

4. It then generates a new access token and links the permission set to this new token.

5. Finally, it returns a response in the following format:

   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
   }

6. The Third-Party Server stores securely the new access token and is now able to make API requests using this new token.

Making API Requests

Once the Third-Party Server 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: