All other applications and plugins

Updated March 13th 2017

Add PixelPin for a simple and secure way to access your site.

PixelPin for All Other Applications & Plugins

If you cannot obtain an OpenID Connect plugin for the technology you are using or you need to extend an existing plugin/application to support PixelPin, you can access the system by using the following instructions. Please note it is HIGHLY recommended that you use an existing plugin where possible or at least use one, such as HybridAuth, as a basis for your own code to ensure that you check all of the variables involved in the handshake and ensure the connection has not been tampered with or hijacked.

The OpenID Connect Core specification can be found here and this should be the basis of your code. Note that PixelPin acts as both an authentication and resource server for the purposes of the specification and that we do not support refresh tokens.

Handshake Description

If you have a fully-featured OpenID Connect plugin, you should be able to point it at the metadata (auto-configuration) endpoint at:

https://login.pixelpin.io/

Doing this will automatically configure all of the following settings instead of setting them up manually.

Browser Redirect

Once you have created a developer account on the dashboard, the first step of the handshake is to redirect the browser to

https://login.pixelpin.io/connect/authorize

You must pass 4 mandatory and 1 recommended querystring parameters. These are:

  1. scope - one or more space-separated scope values describing what information you want to obtain. Must include openid to work fully with OpenID Connect
  2. client_id - the 30 digit alphanumeric code that you obtained when registering the developer account
  3. redirect_uri - the URI that PixelPin needs to return to after authorisation takes place and which you previously registered on your developer account. This can include a querystring, which must be URL-encoded
  4. response_type - The type of response requested by the relying party including code, id_token and token
  5. state (recommended) - a value that will be passed back to the redirect_uri unchanged which can be used to track the request

There are other optional parameters that you can set for more advanced operation, which can be found in the OpenID Connect Core specification section 3.1.2.1

Obivously, you will need some handler at the end of the redirect_uri on your site that can act on a GET request (or a POST if you use a different response_mode) although it does not have to be a page. This handler will be passed different things depending on whether an error occurred or not. If an error occurs but the redirect_uri is invalid for some reason then an error will be displayed to the user and the browser will not redirect back. If the error is unrelated to the redirect_uri, the redirect_uri will be called and passed error=[some error] and optionally error_description, error_uri and the state you passed into the original request. If the authentication process was successful, the redirect_uri will be passed an alphanumeric code (if response_type = code)and the state if it was passed into the original request.

NOTE: This code is NOT the token you need to access the user and will only be valid for a short time in order to complete the handshake.

The other common mode is called hybrid and occurs when you set response_type=id_token, in which case, you will not receive a code but an encrypted json web token, which directly contains the user data. There is no further handshake after this but the work required to implement this manually is beyond the scope of this article.

If the redirect_uri is passed an error, it is up to you to ensure that suitable action is taken depending on the error passed back.

Get Access Token

If a code is returned, this implies that authentication was successful, your site should then setup a POST request to

https://login.pixelpin.io/connect/token

with the following form-encoded values:

  1. client_id - the 30 digit alphanumeric code that you obtained when registering the developer account
  2. client_secret - the 30 digit code that you also obtained when registering the developer account
  3. redirect_uri - the registered redirect uri (this is not used for redirection at this point)
  4. code - the code you received from the original browser redirect
  5. grant_type=authorization_code - the only type PixelPin supports

If this call is successful, you will receive a JSON encoded string with access_token and expires_in. If it fails, you will receive an HTTP error code and description.

If an error is returned, your site must gracefully handle this for the user. The most likely cause of this happening (if it has worked before) is that the service is temporarily unavailable.

Get User Data

If the previous call succeeds, OpenID Connect says you can contact the resource server for user data. In the case of PixelPin, this is the same web application so you should make another GET or POST request to

https://login.pixelpin.io/connect/userinfo

For either GET or POST, you should pass the previously obtained access token as a Bearer authentication header in the format Authorization: Bearer access_token_value See here for details

For POST ONLY you can pass the access token in form data (application/x-www-form-urlencoded) with the parameter name access_token

Note that these restrictions are due to the library we use for OpenID Connect but please contact us if you feel these are overly restrictive.

The token is valid for 30 days, after which an attempt to retrieve the user's data again will fail and which point you will need to follow the complete flow again.

If this call succeeds, it will return a JSON encoded string with values for email, firstName and id (which is a 64 bit numeric id). The firstName might be just a first name, a full name or a nickname used when sending emails to the user. You can use the ID to uniquely identify a user on PixelPin or link the accounts with the email address (which might be changed on the account in the future).