Welcome to the ESA Space Weather Service Network
Please note that all ESA-SWE Services are under review/construction

SSO and M2M

SSO and Machine-to-Machine Interfaces (M2M)

The following section is a description of a technical solution, which has been demonstrated as a successful way to combine the SSO system with M2M interfaces. Nevertheless, this shall not be considered as the only applicable solution, other technical solutions may exist that are equally valid. Note: The ESA SWE network is transitioning to a new SSO system, so this page will change in the near future.

OpenAM Server URL

The URL of ESA’s SSO OpenAM Server is: https://sso.ssa.esa.int:443/am

Session Cookie Name

The session cookie name between the Web Client and the AM Agent Servers is: iPlanetDirectoryPro

General comments

The typical usage of the SSO mechanism involves browsing to a web page, from which the user will be re-directed to the OpenAM server to log in and acquire a valid iPlanetDirectoryPro cookie. This mechanism is by definition not directly applicable to interservice communications using, for instance, RESTful URLs. In order to bypass the redirection to the OpenAM server, the user (a human or a script) needs to obtain a cookie directly from the OpenAM server.

The sections below describe a generic method to query services through REST interfaces which are secured behind the SSO system. This method is applicable to data services as well as model or other services, as long as the service requests are performed using REST URLs.

The server exposing the service to the internet, whether being a Content Proxy or a standalone SSO Agent, will perform the validation of the iPlanetDirectoryPro cookie embedded in the REST request, and only allow the request if it comes from a properly authenticated and authorised user.

OpenAM has supported several versions of APIs over the years. Up to version 12 of OpenAM server, only a single, now deprecated, RESTful API was supported. OpenAM 12 also supports a new API (“JSON API”), which is the new preferred way of interacting with the OpenAM server. New developments shall only use this API, as it is forwards compatible and will continue working even for the latest versions of OpenAM server.

OpenAM RESTful API

The full API documentation can be found on-line at: https://backstage.forgerock.com/docs/openam/13.5/dev-guide/#rest-api-versioning

A quick start guide follows.

The process sequence is as follows:

  1. The user (calling service or script, or a human) acquires a valid SSO token (passed on to the agent as iPlanetDirectoryPro cookie),
  2. The calling service embeds the cookie into a REST query and sends it to the receiving service
  3. The frontend proxy between the service and the internet validates the received SSO token, and verifies that the user is properly authenticated and authorised to access the requested resource,
  4. After receiving the query result, the calling service can logout from the OpenAM server (releasing the cookie). This step is optional, but highly recommended in order to reduce the number of active cookies on the OpenAM server. If multiple service requests are scheduled within a short time frame, it is of course not required to perform a log in and log out for each individual request.

Authentication and Retrieving a token

This shows a cURL request yielding a valid token:
$ curl --request POST --header "Content-Type: application/json" --header "X-OpenAM-Username: demo" --header "X-OpenAM-Password: changeit" --data "{}"

https://sso.ssa.esa.int:443/am/json/authenticate { "tokenId": "AQIC5w...NTcy*", "successUrl": "/am/console" }

Using the token to perform a request on a SWE resource

Again, using cURL, this is how a request to SWE resource would look like:
$ curl -s -G -d “start_date=2018-01-07T13:12:08&output_type=JSON” -b “iPlanetDirectoryPro=AQIC5wM2LY4SfczI_iumAj6_Pdz- VI6e2jkzrxcx9jpV9ko.*AAJTSQACMDE.*” -o output.txt -L https://<web service url>

This is a GET request with two parameters. The query result will be written to a file named output.txt. Please consult the curl manual (e.g. https://gist.github.com/afair/5265874) for further options, which may be required by the service that is being called.

Checking token validity on the server side

To check over REST whether a session token is valid, perform an HTTP POST to the resource URL, /json/sessions/tokenId, using the validate action as shown in the following example:
$ curl --request POST --header "Content-Type: application/json"  https://sso.ssa.esa.int:443/am/json/sessions/AQIC5...?_action=validate

{"valid":true,"uid":"demo","realm":"/myRealm"}

If the session token is not valid, a "valid": false JSON message is returned, as shown below:
$ curl \
--request POST \
--header "Content-Type: application/json" \
https://sso.ssa.esa.int:443/am/json/sessions/AQIC5...?_action=validate

{"valid":false}

Logging out (ending a session)

If a used cookie is no longer required, it should be released by performing a logout:
$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC5wM2...U3MTE4NA..*" \ "
https://sso.ssa.esa.int:443/am/json/sessions/?_action=logout"

{"result":"Successfully logged out"}