| 

Back

OpenId Requirements (version beta 1.0)

The OpenId client or "Relying Party" is the software tool to be intergrated with GenomeSpace, also called "your app" below. The OpenId server or "Provider" is the GenomeSpace server.
The end result of successful OpenId login is, your app will have a valid GenomeSpace token and username, which are needed to access nearly all GenomeSpace web services.
Because token can only come from the GenomeSpace OpenId Provider, it is the only OpenId Provider that will work with GenomeSpace, and not Google, Facebook, Twitter, etc.

Tool Requirements

Client Library

Choose an OpenId client library to use with your app. For Java we recommend

openid4java 0.9.6

For Python we recommend

python-openid 2.5.5 and python 2.6.6

The library needs to support OpenId Version 2.0, and needs to support at least one of these spec extensions: Attribute Exchange ("AX"), Simple Registration ("SReg") version 1.0 or 1.1, or the openId version 2 spec compliant custom extension.

Client code

Your application needs code that calls the OpenId client library to talk OpenId protocol with the GenomeSpace OpenId server. There is Java code in BitBucket"s GenomeSpace/Combined project, called "openIdClient". It's pretty much one Java Servlet and some supporting Jsp, and includes the minimal set of required jars. If you search for "This is where a real app would forward or otherwise connect" you'll find the point in the code where the servlet should redirect to your app upon successful login.

Server URL

The OpenId spec describes how the user starts the login process by supplying a "User-Supplied Identifier". It in turn resolves to the "OpenId Provider Endpoint URL". Since there is only one acceptable provider, your app can always use one User-Supplied Identifier which is a url gotten by HTTP GET from http://www.genomespace.org/sites/genomespacefiles/config/serverurl.properties and extracting the "openIdUrl" property for the desired server.

Extension

Your app's client code needs to request that the GenomeSpace OpenId server return the gs-token and gs-username values. Due to the lack of uniform support among various OpenId libraries, the GenomeSpace OpenId server supports three ways of doing this. Pick any one of the three. It's just a question of what is supported by your OpenId library.

  1. In the OpenId Authentication Request, the client adds a SimpleRegistration request.

    SReg Version 1.0 parameters are:
    openid.sreg.gender
    openid.sreg.nickname

    SReg Version 1.1 parameters are:
    openid.ns:http://specs.openid.net/auth/2.0
    openid.ns.sreg:http://openid.net/extensions/sreg/1.1
    openid.sreg.required:nickname,gender

    The OpenId authentication response from GenomeSpace will contain the gs-token value for sreg gender key, and gs-username for nickname, i.e. the two SReg attributes are re-purposed.
  2. In the OpenId Authentication Request, the client adds an Attribute Exchange FetchRequest with these parameters:
    openid.ns.ext1 = http://openid.net/srv/ax/1.0
    openid.ext1.type.gs-token = http://identity.genomespace.org/openid/gs-token
    openid.ext1.type.gs-username = http://identity.genomespace.org/openid/gs-username
    openid.ext1.ifavailable = gs-token,gs-username
    From the OpenId authentication response, the client gets the gs-token and gs-username from the FetchResponse.
  3. When the OpenId client makes neither of the above parameter requests, the GenomeSpace OpenId provider will supply gs-token and gs-username in a OpenId custom extension. Nothing is required from the client in the auth request, and the client can get gs-token and gs-username from the validated response from these OpenId key-value pairs:
    openid.ns.ext1:http://identity.genomespace.org/token
    openid.ext1.gs-username:<the GenomeSpace username>
    openid.ext1.gs-token:<the GenomeSpace token>

Retrieving email address

If your app wants the user's email address, the client should request the user's email address in the OpenId Authentication Request. It is best to use the same mechanism that was used to request gs-token and gs-username. The added OpenId message parameters are:

  1. With Attribute Exchange:
    openid.ext1.type.email = http://identity.genomespace.org/openid/email
    openid.ext1.ifavailable = gs-token,gs-username,email
  2. With Simple Registration

    SReg 1.0:
    openid.sreg.email

    SReg 1.1:
    openid.sreg.optional:email
  3.  
  4. With GenomeSpace custom extension, the Authentication Response will contain:
    openid.ext1.email:<the GenomeSpace user email>

Logout

OpenId logout is possible but requires both of these steps to be done: