The Login mechanism

The first thing for a Viewer to do is to login to the Agent Domain. In order to be able to do this it needs to know how this can be done.

We assume the Viewer has the main URL for the Agent Domain. This could e.g. be some webpage with information about this service.

For the login to work the Agent Domain MUST provide Service Discovery on that URL based on XRDS-Simple.

The Agent Domain CAN provide as many login methods as it wants but it MUST at least implement Basic Authentication, identified by the Type URI

http://opengridprotocol.info/alternative/login/basicauth/1.0

The Viewer MUST implement at least Basic Authentication.

The login mechanism then works as follows:

1. The Viewer MUST initiate an XRDS service Discovery on the Agent Domain URL
2. The Agent Domain MUST return a document describing the various login methos it supports
3. The Viewer chooses the one with the lowest priority number (which means highest priority) it supports.
4. The Viewer starts the login process with the login method choosen. The individual methods are describes further below.
5. Once it is authenticated it will receive an XRDS-Simple document describing all the service available to the Viewer.
6. Additionally the Agent Domain MUST add a cookie to the response which the Viewer then at further requests MUST include in them.

Note

We have choosen to use a cookie instead of a separate header as most web frameworks on top of which you most likely implement an Agent Domain already have good support for this kind of thing.

After that the login process is finished.

Error handling

In case an error occurs during login the Agent Domain returns a 401 Unauthorized and the response body contains an explanation of what went wrong.

Note

In OGP this is now a separate message and the return code is 200. It’s debatable what mechanism is better as there are no big differences.

Login Methods

Registration of new accounts is out of scope of this protocol specification. It can e.g. be done by a simple web form. Usernames are also free to choose for an Agent Domain, it can be Firstname/Lastname but it does not need to be. It’s also up to the Agent Domain impementation of how the username is encoded for authentication purposes. E.g. firstname/lastname pairs might be combined by space or underscore or it might even be a completely separate username used than later for the agent.

The following login methods are defined:

Basic Authentication

Type URI: http://opengridprotocol.info/alternative/login/basicauth/1.0

The process is the same as Basic Authentication in HTTP:

1. The Viewer connects to the given login URL and adds an Authorization: header to the request.
2. The Agent Domain checks the credentials and issues an 200 OK with an XRDS document. In case of an authentication error it will return 401 Unauthorized with an WWW-Authenticate header.

Open ID

TBD

Maintenance

Sometimes it is necessary to perform maintenance tasks during the login process. In order to check if such tasks have to been done, the Viewer MUST check the XRDS service file for the Type URI

http://opengridprotocol.info/alternative/login/maintenance/1.0

It then issues a GET request on the according service URI and obtains a Maintanance message similar to the one in OGP (encoded in JSON).

Comments