This chapter provides a general specification for OAuth Gateway type network services. It contains these sections:

Service Overview

The OAuth Gateway type service is responsible for handling the redirect portion of the OAuth 2.0 protocol when the MediaBar needs to access systems that use that authentication mechanism. This service can be address using the type "com.openmethods.ep.oauth.gateway".

Service Specific Information

Each registered service has information specific to its service type, vendor, or instance. This information is available through the getServices Core Request or as part of the events produced by the Service Monitor Service.

{
  "vendor", "<vendor-name>",
  "version", "<current-version>"
}

Service Requests and Responses

This section documents the requests that interaction processors must support and the responses that should be returned.

registerClient

The registerClient request is used by a client to initialize a new session on this gateway. The session's unique identifier is included in the response so the client can easily bind to the session resource. The client provides the contents of the oauth.settings block as-is in the data property. These values are used by the gateway to interact with the environment's OAuth provider.

Request

{
  "command": "registerClient",
  "data":
  {
    <contains the environment object>
  }
}

Success Response

{
  "command": "registerClient",
  "result": "success",
  "resource":
  {
    "id": "<resource-id>",
    "data":
    {
      <Contains the original data property of the request>
    }
  }
}

Failure Response

{
  "command": "registerClient",
  "result": "failure",
  "failure":
  {
    "code": "<error-code-for-failure>",
    "message": "<error-message>",
    "context": "<stack-trace-if-applicable>"
  },
  "original":
  {
    <Contains the original registerClient request JSON structure>
  }
}

Secondary Events

This request should not generate any secondary service events.

Service Events

The basic OAuth Gateway type service does not generate service events.

Session Resource

A session resource represents an active client session that can receive redirect requests from an OAuth 2.0 login server.

Session Resource Messages

Session resources will only produce a single event when a valid OAuth redirection request is made. This request is matched to the proper session resource based on the state field which should contain this session resource's unique identifier.

Session Events

Auth Token

Delivers the authorization token for this session.

{
  "access_token":"<access_token>",
  "token_type":"bearer",
  "expires_in": <number_of_seconds>
}

Harmony

OAuth Gateway Service