All other applications and plugins
Updated April 16th 2018
Add PixelPin for a simple and secure way to access your site.
- PixelPin for All Other Applications & Plugins
- Handshake Description
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.
If you have a fully-featured OpenID Connect plugin, you should be able to point it at the metadata (auto-configuration) endpoint at:
Doing this will automatically configure all of the following settings instead of setting them up manually.
Once you have created a developer account on the dashboard, the first step of the handshake is to redirect the browser to:
You must pass 4 mandatory and 1 recommended query string parameters. These are:
- scope - One or more space-separated scope values describing what information you want to obtain. Must include openid to work fully with OpenID Connect.
- client_id - The 30 digit alphanumeric code that you obtained when registering the developer account.
- 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 query string, which must be URL-encoded.
- response_type - The type of response requested by the relying party including code, id_token and token.
- state (recommended) - A value that will be passed back to the redirect_uri unchanged which can be used to track the request.
Example Authorize request:
GET /connect/authorize? client_id=7FQ3PWIEILPQR1YGCTV0DF7S3I78B2 scope=openid email profile& response_type=code& redirect_uri=https://www.example.com/signin-pixelpin& state=CfDJ8H2uVx21tnlFu Host: login.pixelpin.io
There's a optional query string parameter that we support that could improve your user's experience while using PixelPin:
- prompt (optional) - A value that specifies whether PixelPin prompts the user for (re)authentication and consent. The values that can be set are:
- none - PixelPin will not display any authentication or consent user interface pages. An error is returned if the user is not already authenticated or the Client does not have a pre-configured consent for the requested Claims or does not fulfill other conditions for processing the request. The full list of error codes can be found in Section 220.127.116.11 of the OpenID Connect Core 1.0 specification. This value can be used as a method to check for existing authentication and/or consent.
- login - PixelPin should prompt the user for (re)authentication, regardless of their authentication status. If PixelPin cannot (re)authenticate the user, an error of login_required is likely to be returned.
- Check the JWT returned by the https://login.pixelpin.io/connect/token endpoint to see if it contains a auth_time claim.
- If auth_time is greater than the login journey start time, (which you need to implement) then the user has reauthenticated successfully.
- If auth_time is smaller than the login journey start time, then you'll need to redirect the user to login again and re-check the auth_time.
- consent - PixelPin should prompt the user for consent before returning information to the Client, regardless of their consent status. If PixelPin cannot obtain consent, an error of consent_required is likely to be returned.
SECURITY NOTE: Authenticated users can bypass prompt=login by removing the prompt=login parameter to prevent themselves from being re-authenticated. Follow these steps to avoid this from happening:
Example Authorize request with prompt parameter:
GET /connect/authorize? client_id=7FQ3PWIEILPQR1YGCTV0DF7S3I78B2 scope=openid email profile& response_type=code& redirect_uri=https://www.example.com/signin-pixelpin& prompt=login& state=CfDJ8H2uVx21tnlFu Host: login.pixelpin.io
NOTE: Currently, we do not support the prompt select_account parameter.
NOTE: Currently, we do not support the use of multiple prompt parameters to be used in a single authentication 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 18.104.22.168.
Obviously, 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
with the following form-encoded values:
- client_id - The 30 digit alphanumeric code that you obtained when registering the developer account
- client_secret - The 30 digit code that you also obtained when registering the developer account
- redirect_uri - The registered Redirect URI (this is not used for redirection at this point)
- code - The code you received from the original browser redirect
- 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
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).