API key and webservices access rights.

We describe here how to use directly an API key on the Géoportail API webservices. This documentation addresses developers wanting to request directly the WMS-C service in a third party client application (not provided by IGN). The following right management schema is implemented in the file Geoportal/GeoRMHandler.js of the provided javascript web client.

Principle

Each request to servers contains a token allowing access to data. The token encodes access rights and identifies a user session. It is obtained and updated from a token server.

What is a token ?

A token is a short term access parameter associated with an API key. It represents a user session and contains access rights of the API contract. The token should be added to each API request as a characters string in a url parameter (currently gppkey).

The token server.

The Géoportail API token server is jeton-api.ign.fr. It provides services to create, update and release an API session (token).

Method getToken

This service creates or updates a token.

  • Parameter key (first request) : API contract key ;
  • Parameter gppkey (update) : The token of the session to update. The token is sent as a url parameter or a cookie ;
  • Parameter output (optional) : The output format amongst : xml (default), json or raw ;
  • Parameter callback (optional) : Only for json format. Specify a callback function ;
  • Parameter cookie (optional) : The token is sent back as a cookie in addition to the normal format in the body of the HTTP response.
  • In case of success The answer contains the token (characters string) and the name of the url parameter (or the cookie name). This url parameter name should be used in all API requests, including token updates on the token server. The token received gives an access to the services associated with the API contract during a short period of time (currently 10 mn).

    Example: http://jeton-api.ign.fr/getToken?key=KEY&output=xml

    <token name="gppkey">
  gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAABHiB
  QmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA
</token>

    Example: http://jeton-api.ign.fr/getToken?key=KEY&output=json

    {
  "gppkey":"gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAA
  BHiBQmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA"
}

    Example: http://jeton-api.ign.fr/getToken?key=KEY&output=json&callback=myfunc

    myfunc({
  "gppkey":"gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAA
  BHiBQmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA"
});

    Example: http://jeton-api.ign.fr/getToken?key=KEY&output=raw

    gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAABHiB
QmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA

    Exemple: http://jeton-api.ign.fr/getToken?key=CLEF&gppkey=gC2UZ...AAA&output=xml (update)

    <token name="gppkey">
  37mZE3sL-EuU5GAvG2NFwXZaRLgAAAAAAJG_bR0eku1hUp-bAAABK
  OBRtx4AAAAAAlgAAQEBzIOB9cN7vYDDNAAAQzQAAMK0AABCtAAA
</token>
  • In case of failure A HTTP 403 error is sent back. There are several possible causes :
    • invalid key or token.
    • maximal simultaneous sessions number reached for a given contract.
    • invalid IP or REFERER (according to the contract)
    • global overload of the service

Method releaseToken

  • Parameter a token : indicate an active session to release

    The token of a released session can no more be used in API calls. Although this operation is supported, it does nothing at the writing of this documentation.

    Example: http://jeton-api.ign.fr/releaseToken?gppkey=gC...AA

Method getConfig

  • Parameter key : a API contract key.

    This service provides in xml an json format the following information :

    • token living time
    • Geographic extent of the contract
    • Available resources list (server / service / layers)

    Example: http://jeton-api.ign.fr/getConfig?key=KEY&output=xml

    <config>
  <tokenTimeOut>time in seconds</tokenTimeOut>
  <boundingBox minx="west longitude"
               miny="south latitude"
               maxx="east longitude"
               maxy="north latitude"/>
  <resources>
    <resource>
      <name>layer</name>
      <type>WMSC, WMS, WFS, ...</type>
      <url>Service's URL</url>
    </resource>
    ...
  </resources>
</config>

    Exemple: http://jeton-api.ign.fr/getConfig?key=CLEF&output=json

    {
  "tokenTimeOut":time in seconds,
  "boundingBox":{
    "minx":west longitude,
    "miny":south latitude,
    "maxx":east longitude,
    "maxy":north latitude
  },
  "resources":[
    {
      "name":"layer",
      "type":"WMSC, WMS, WFS, ...",
      "url":"Service's URL"
    },
    ...
  ]}

Using a token on API services.

Every HTTP request to a GeoDRM protected service must contain a valid token as a HTTP header or as a url parameter or as a cookie. The url parameter is checked before the cookie, which in turn is checked before the HTTP header when several forms of the token exist in the request. The request is filtered according to the access rights of the API contract.

A token may contain the following access rights : available resources (services, layers), A geographic extent (optional), an IP (optional), referers (optional).

In case of error, and 403 HTTP error is sent.

Notes :

  • For local developments, all keys work with "localhost" and "127.0.0.1" REFERERs.
  • An incompatibility with HTTPS protocol is known because of the missing REFERER HTTP header. Therefore, the support of HTTPS for the GeoRM is not activated.

New upcoming GeoDRM

Principle

Each request to servers is sent with an access key which use a specific authentication process (see next section). A key is represented by an 24 characters long alpha-numeric string.

A key grants access to a set of services. These services can be reached using URL that match the following pattern :

        wxs.ign.fr/context/service

Key must be inserted in the URL, between the domain name and the service path. Here is the result :

        wxs.ign.fr/KEY/context/service

There may be up to 3 different contexts for each service :

  • geoportail : data served by Geoportal infrastructure. Data use is under IGN terms and conditions ;
  • inspire : INSPIRE compliant data served by Geoportal infrastructure. Data use is under INSPIRE terms and conditions ;
  • edugeo : data for Education National (french school administration) served by Geoportal infrastructure. Data use is under specific conditions.

    URL examples : +-- wxs.ign.fr/KEY/geoportail/wms wxs.ign.fr/KEY/inspire/wfs +--

Keys

There are two types of keys :

  • Keys based on Referer/IP/User-Agent. Authentication is made against one or more of these 3 criteria. Some keys authenticates only against the Referer header contained in HTTP requests. Some other keys, authenticate against both IP address and User-Agent HTTP header. Any combination of Referer, IP and User-Agent can be used to authenticate a key ;
  • Key based on login/password. Authentication is made using HTTP Basic authentication. The login and password are encrypted in the Authorization header of HTTP requests. In order to use this type of key, the developer needs to know the login/password associated with his key. It is recommanded to use the HTTPS protocol for such a key type.

    If authentication fails, a HTTP 403 error will be returned by web services. A HTTP 401 error may be returned when using a login/password key without specifying the Authorization header. The web browser will display a popup window asking for login and password.

Available web services

Below is a sample list of Geoportal web services under the GeoDRM protection :

  • WMS version 1.3.0
  • WFS version 2.0.0
  • WMTS version 1.0.0
  • OpenLS version 1.2.0
  • CSW ISO API version 2.0.2
  • Altimetric service
  • Tiled vector (KML)
  • KML/Collada (3D objects)

Available resources - APIs autoconfiguration

This new service will be made available as "auto-configuration service". Given one or more contracts keys, it will give access to information such as :

  • parameters for default visualisation in a web page (dimensions, territories, layers to display, ...) ;
  • technical parameters for geoportal services ( WMTS TileMatrixSets, resolutions lists, territories configuration, bounding boxes, ...) ;
  • available resources (layers) and information about them (url, bounding boxes, scales, ...).

Service access

One may invoke the service that way :

        wxs.ign.fr/KEY/autoconf/?keys=KEY,KEY2,...

where KEY, KEY2, ... are the contract keys. If no key is given, the description of the whole geoportal resources will be returned.

Service response

Service response is an XML document which inherits from Web Map Context OGC standard. Below is a quicklook of the document structure.

Service use

All IGN's web APIs will make use of this service to configure web map applications transparently for the web developer.

For a standalone application (GIS, mobile...), the developer will have to handle access to this service by his own, if needed.