Application Session

Purpose of the Application Session

Before the Provider's Application can offer the "Login by Open Console" service, it need to authenticate itself. One of the main reasons to require this dynamic Session, is to hide internal static Open Console identifiers from the nasty outside world. Internal identifiers will live long, external identifiers live short.

Logging-in for the Application

The Application of the Provider relates to (one or more) Service definitions in Open Console. When a Service definition is created, it will create a bearer $service_token. You need to copy this token into the configuration of your Application.

First, send this REST message:

  POST /application/login
  Host: $oc_connect(host)
  Authentication: Bearer $service_token
  Content-Type: application/json

  {  "secret": "your server secret",
     "instance":  "your instance identification",
     "api_version": "1.0.0",
     "jwt": false,
  }

The api_version tells the connect server which version of the API you implemented. The server will try to give you some additional backward compatibility. Open Console may send you an email when it detects that support for your API version will change.

The jwt=false optional parameter flags whether JWT for Oauth2 (RFC9068) is supported by the client. On the moment, this is not implemented. The default is false.

Its response will be something like

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=UTF-8

  {
    'connect': {
       'api-version': '1.0.0',
       'instance': 'cd001',
    },
    'session': {
       'bearer': $app_session,    # this is important: the Session ID
       'created': $now,
       'expires': $expires,       # YYYY-mm-DDTHH:MM:SSZ  (always Zulu time)
    },
    'service': {                  # some convenience service information
       'name': 'My AppName in OC'
    },
    'endpoints': {                 # configuration of Open Console Connect
       'user_login':    $myaccess,    # absolute URL (access_token_path)
       'refresh_login': $myrefresh,   # absolute URL (refresh_token_path)
       'user_info':     $myuserinfo,  # absolute URL (userinfo_path)
       'owner_website': $myowner      # absolute URL
    }
  }

The Application can use the $app_session (ID) until it $expires (DateTime in Zulu). Expiration is in the order of 24 hours. You may establish multiple visitor logins with this single Session, and keep them in your database.

The Provider may create multiple Sessions for the same Service. For instance, when you run the Application on multiple hosts, each instance should create its own Session.

Log-out for the Application

When you do not need a Session anymore, you MAY explicitly remove it: when leaked, no-one will be able to use it anymore.

  GET /application/logout?grace=P24H
  Host: $oc_connect
  Authentication: Bearer $app_session

Be aware that people may still be using this $app_session to login, because it is used in the link for the "login" button in the visitor's browser. Therefore, you can add a grace period (an ISO8601 Duration). Open Console will keep the application session active until the grace period is over. The default grace period is P1D (one day).

Meanwhile, the application must have logged-in again, to use a new session bearer key.

This leads to a response like

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=UTF-8

  {
    'grace_end': '2026-03-08T12:12:12Z'
  }

Generic Application Errors

The application handles it back-channel communication via a REST interface.

When a 5XX response is received, then usually a text/html body is included. For all other response codes, an application/json is contained. When the response code is HTTP_OK (200), then the REST call has produced its expected result. Otherwise, the response is an error.

Error replies look like this:

HTTP/1.0 400 Bad Request
Content-Type: application/json

{ "ErrorCode": 400,
  "Message": "The code is not a comply id."
}

Generic Application Session Errors

After login, all requests will carry an Authentication header, containing Bearer $token. The $token is the $session->{session}{bearer}.

Besides issues with handling specific requests, there are also issues which are generic for any REST call... usually related to the Baerer token.

• HTTP_UNAUTHORIZED (401), Authorization header missing or incorrectly formatted
• HTTP_BAD_REQUEST (400), the bearer token is either not native to Open Console, or not an appsession token
• HTTP_GONE (410), the token seems valid, but cannot be found in the database (anymore)
• HTTP_UPGRADE_REQUIRED (426), the session has expired: call appLogin again