Updated September 15th 2020
- In order to add PixelPin as a connection to your Auth0 account, you must be on an enterprise plan.
Create a new OpenIdConnect enterprise connection
Log in to your Auth0 account, navigate to the Authentication -> Enterprise page and click the + symbol next to "Open ID Connect".
Enter the following information into the New Open ID Connect Connection screen and then click Create:
- Connection name - This can be anything that will easily identify this connection within your account. We'll use "PixelPin" here.
- Display name - This is the name as seen by your users and as such should be "PixelPin"
- Logo URL - We recommend using "https://developer-assets.pixelpin.net/logos/pixelpin_logo_20.png" for this
- Issuer URL - The needs to point at PixelPin's API and will allow Auth0 to auto-discover the rest of the required information:
- For sandbox use: https://api.sandbox.pixelpin.net
- For production use: https://api.login.pixelpin.io
- Client ID - This is your PixelPin client ID. Instructions for acquiring a client ID can be found here. When creating your developer account with PixelPin be sure to use the value displayed in Callback URL as your Redirect URI.
Once the connection has been created, more options will appear at the bottom of the form. Fill these in as so:
- Type - Select "Back Channel". This will cause a Client Secret field to appear.
- Client Secret - This is your PixelPin Client Secret to match the client created above.
- Scopes - The default value is likely fine here and should be "openid profile email", you can tweak this for your needs, however "openid" is required to be present in the list.
Configure your application
How you configure your Auth0 application now depends on your technology stack, but Auth0 have a range of getting started guides available. See the image below for more info.
Once you have your application set up, the PixelPin connection we set up in step 1 should appear in the Connections tab. Simply turn this on and you're ready to authenticate your Auth0 application users with PixelPin.
A note on using PixelPin as one of many authentication methods
At the time of writing, new Auth0 apps default to the Classic login experience. In this mode, only one provider will be shown, which by default is the username and password field. This is because Auth0 will attempt to guess the provider to use based on the email entered by the user.
In order to display a button for each enabled provider you will need to enable the new Universal Login experience. This can be enabled under Branding -> Universal Login as seen below, and will display a button for each provider you have enabled.
Further customisation of the login prompt in Auth0 is beyond the scope of this documentation.
A note on user merging when using multiple authentication methods
Each time a user authenticates via Auth0 with a particular authentication method they are given an ID specific to them and the authentication method used. It's this ID that's then used to create/lookup their account. This does however mean that if a user who previously registered with your site via a username and password later decides to use PixelPin instead, they will be given a brand new account (not including any roles, permissions etc of the original account).
There are a few ways to get around this, all of which are detailed in the following Auth0 article: https://auth0.com/docs/users/user-account-linking.