Skip to content

registration.md

Latest commit

 

History

History
77 lines (61 loc) · 3.66 KB

registration.md

File metadata and controls

77 lines (61 loc) · 3.66 KB

Registering your Cloud Provider with openEQUELLA

In order to run a cloud provider service you must provide a web page which can accept a cloud provider registration request. This is the URL that openEQUELLA administrators will enter as the registration URL. Let's use a server running on localhost as an example:

http://localhost:8080/providerlogon.html

This page is where you should authenticate that the user has access to your cloud provider service or just a friendly message if you are hosting a free public service. If the user is allowed to access your service you can then register with the openEQUELLA that initiated the registration request.

In order to complete the registration you should use the two parameters generated by openEQUELLA and appended to your registration web page URL:

  • institution - The institution URL requesting the registration.
  • register - An opaque institution relative URI which you must POST a cloud provider JSON registration to. This URL can only be used once and will expire within an hour.

An example URL initial URL would be:

http://localhost:8080/providerlogon.html?institution=http://equella.com/inst/&register=api/cloudprovider/register%3Ftoken=TOKENVALUE

Which would mean you should POST your registration to:

http://equella.com/inst/api/cloudprovider/register?token=TOKENVALUE

If your registration is successful you will receive a JSON registration response (ProviderRegistrationResponse) which contains:

  • The full cloud provider registration JSON, which will include the "provider id" and oauth credentials for authenticating into the openEQUELLA instance.
  • A forward URL to redirect the browser back into openEQUELLA.

TODO: A diagram of the registration flow would be good.

Cloud Provider Registration data

The format of the registration JSON is available in a typescript defintion file here (ProviderRegistration).

{
  "name": "My Cloud Provider",
  "description": "My sample cloud provider, including wizard controls",
  "vendorId": "myvendor",
  "baseUrl": "http://localhost:5000/",
  "iconUrl": "https://user-images.githubusercontent.com/4625498/55527161-8591ca80-56e3-11e9-8865-ca7c3bc5b7f2.gif",
  "providerAuth": {
    "clientId": "universityid",
    "clientSecret": "universitysecret"
  },
  "serviceUrls": {
    "oauth": {
      "url": "${baseUrl}oauthtoken",
      "authenticated": false
    },
    "refresh": {
      "url": "${baseUrl}refresh",
      "authenticated": false
    },
    "controls": {
      "url": "${baseUrl}controls",
      "authenticated": false
    },
    "control_omdb": {
      "url": "${baseUrl}omdb.js",
      "authenticated": false
    }
  },
  "viewers": {
    "myattachment": {
      "": {
        "name": "Default viewer",
        "serviceId": "viewattachment"
      }
    }
  }
}
  • name, description, and iconUrl are used for presentation inside openEQUELLA.
  • providerAuth provides openEQUELLA with credentials which are used to securely call services within your cloud provider. It is up to the cloud provider to associate the credentials with an institution and can be used to determine what services the cloud provider supports within that institution. For example, the cloud provider might support multiple wizard controls but might only want to allow a subset of them depending on which institution is accessing them.
  • serviceUrls - This is a map of Service Id to URL template. Some Service Ids have pre-defined meanings and expect request/responses in a certain format, they are documented in the services page.
  • viewers - This is a map of cloud provider attachment type to viewer definition. It is described on the attachments page.