OAuth

The Planviewer Maps API implements an OAuth 2.0 client as per RFC6749.

When under ‘Beveiliging en toegang’ an OAuth configuration is set, all /maps_api/v1/embed calls require authentication via OAuth (contrary to being publicly accessible). Planviewer Maps API acts as an OAuth client, and tries to get authorization for the user from an OAuth provider to view and edit the maps associated with the application.

Important

Any user that is succesfully authenticated gains access to the application. The Planviewer Maps API does not check for roles associated with the user to determine if a user has access to the application or a specific map.

Once authenticated, the authorization (see Access Token) is stored in the server side session of Planviewer.

Glossary

OAuth provider
The party to which Planviewer tries to authenticate the user. The provider typically also implements the Planviewer Maps API.
OAuth client
Planviewer Maps API acts as an OAuth client in this scheme. The Planviewer ‘application’ tries to get authorization for the user to use the maps associated with the application.
OAuth user
The user visiting an embed call (i.e. a viewer or an editor). This user needs to be authenticated by the OAuth provider, so that the OAuth client knows that the assets should be available to the user.
Client Id
Public identifier of Planviewer which it uses to authenticate itself to the OAuth provider as an OAuth client application.
Client Secret
The private secret Planviewer uses to authenticate itself. See Client Id.
Authorisatie URL
The provider URL to which the first authorization request is made.
Access Token URL
The provider URL to generate an Access Token.
Resource URL
The provider URL to fetch the resources associated with the user. Currently this is not actively used by Planviewer, but the OAuth 2.0 specification requires its existence.
Access Token
An unique string generated by the OAuth provider identifying the user on the provider side. It does not defacto identify who the user is, only that is an authorized user.

How to implement

Any standards compliant OAuth provider should automagically work with the Planviewer Maps API. Note that only Bearer and MAC token types are supported as of yet. For concrete instructions we refer to RFC6749.

Step-by-step example

For your convenience we will now go through an authentication routine step-by-step.

Warning

This walkthrough is not a substitute for the standard. We suggest using a reputable open source implementation of OAuth for your OAuth provider. If you intend to implement the provider yourself refer to RFC6749.

_images/oauth2sequencediagram.png

Request application page

GET https://www.planviewer.nl/maps_api/v1/embed/map/(string: identifier)

Browser requests a map from an application which has OAuth enabled. The browser is redirected to the OAuth providers’ authorization server.

Response Headers:
 
  • Set-CookiePHPSESSID If not yet the case, a session cookie is set.
  • Location – Redirect to Authorisatie URL: https://provider/authorize/?state=...&client_id=...&redirect_uri=...&...

Request login

GET https://provider/authorize/?state=...&client_id=...&redirect_uri=...&...

Browser follows the redirect to the authorization server, where a login page might be shown. The method by which the provider authenticates the browser is not defined. The browser could also be authenticated using a previously set session cookie, or an IP whitelist.

Query Parameters:
 
  • state (string) – State string as defined by the OAuth client
  • response_type (string) – Defaults to code, see the standard for more information
  • approval_prompt (string) – Defaults to auto, see the standard for more information
  • client_id (string) – As set in the OAuth configuration page, see Client Id
  • redirect_uri (string) – Callback URL to return to after authorization is completed (or failed)

After the authentication is completed, the browser is redirected back to the OAuth client:

Response Headers:
 
  • Location – Redirect to the Callback URL: https://www.planviewer.nl/maps_api/v1/oauth/1/callback?code=...

User valid and authorized access

GET https://www.planviewer.nl/maps_api/v1/oauth/1/callback?code=...
Query Parameters:
 
  • code (string) – Authorization Code
Status Codes:
  • 200 OK – no error, page is served
  • 403 Forbidden – authorization code does not yield a valid Access Token

The Authorization Code is used to retrieve an Access Token from the Authorization server. The OAuth client performs several requests in the background to validate this Authorization Code.

Get Access Token

This request is performed by the OAuth client to the Access Token URL as set in the OAuth configuration page.

POST https://provider/access_token
Form Parameters:
 
  • string grant_type – Set to authorization_code.
  • string codeAuthorization Code
  • string redirect_uri – Original redirect_uri as set during the Request login phase.
  • string client_id – As set in the OAuth configuration page, see Client Id.
Response JSON Object:
 
  • access_token (string) – Access Token issued by the authorization server
  • token_type (string) – token type as per standard
  • expires_in (integer) – (recommended) the lifetime in seconds of the Access Token.
  • refresh_token (string) – Can be used to obtain new access tokens using the refresh_token authorization grant.

Example response:

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
}

Get data

This request is performed by the OAuth client to the Resource URL as set in the OAuth configuration page. The contents of the response is currently not used by the OAuth client. However the resources are still retrieved. The resource server should check whether the Access Token is valid.

GET https://provider/resource

The method in which the OAuth client utilizes the Access Token to authenticate with the resource server depends on the token_type. Typically, it involves using the HTTP “Authorization” request header field. Currently we only support the “Bearer” and “MAC” token types.

Example request:

GET /resource
Host: provider
Authorization: Bearer mF_9.B5f-4.1JqM