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.
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.
- 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.
- 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.
For your convenience we will now go through an authentication routine step-by-step.
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.
Request application page¶
Browser requests a map from an application which has OAuth enabled. The browser is redirected to the OAuth providers’ authorization server.
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.
- 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:
- Location – Redirect to the Callback URL: