Integrating your authentication platform

With Pugpig you can integrate with your own authentication or subscription platform to manage user access to your content. Users might exist in a third party subscription system or a database you manage. As standard we provide out of the box integrations for some of the larger, well known subscription systems, and we have a full list of our supported 3rd party providers. If yours isn’t supported don’t panic... we also provide a tried and tested pattern for integration.

Important: If you are using a web based authentication OAuth/PKCE flow for the sign step (which we recommend) instead of a direct API call, you will also need to read and understand Web-based authentication integrations in Pugpig apps using PKCE.

Pugpig Authentication Setup Pack

1. In advance of starting work we require this information from you.
2. To kick off we will arrange an initial call to discuss your authentication requirements and API documentation including the auth parameters (e.g username, email, password etc). Your API needs to be available to us over HTTP(S).
3. We will supply our IP range to you if you need to restrict access to your API endpoints.
4. Following this, we usually build a proxy to your API (before we can write this we will need all the items outlined above).
5. We will then build a third party authentication module (hosted on our Distribution platform) which talks to your third party API.
6. Next up we will need to configure and add the third party authentication into the app containers.
7. You will need to supply test users that cover each scenario, we will then add a test form and test the third party authentication with users provided in browser and on devices.
8. Our system will automatically run tests every evening, and log an error if it isn't behaving as it should.
9. We will also handle the setting up of the SSL certificates so that communication between the apps is secure.
10. Your Pugpig Authentication support package will be available until your app is ready to submit during which time you will have priority ticket support.
11. Any additional help required, as well as post launch support can be purchased under our standard support agreement.

Structure of your API

At a high level, the APIs look something like this:

• A sign in method. The inputs will be the user credentials (for example email address and password). We can also pass a unique device ID and the originating IP address if these are useful. The API normally returns a user token which can be used in the entitlements method.
  This will normally be an HTTPS POST (as GETs often end up in web server logs, and these requests contain passwords often). This is called every time a user logs into the app. 
  This sign in method is NOT needed if you are implementing a PKCE flow
• An entitlements method. The input for this will normally be the user token supplied by sign in or the PKCE flow. The response should indicate the entitlements a user has.
  The response could also indicate that we may need to call a token renew endpoint.
  This is called every time a user opens the app
• An token renew method. This is optional, but needed if we need to renew stale tokens.

We can support REST (preferred) or SOAP and the responses are ideally JSON (preferred) or XML.

Frequently Asked Questions

Q: Can I include a user ID or some other data in my app analytics.
A: Yes - just let us know which fields you'd like sent to the analytics as an extra dimension. Note that we don't recommend sending identifiable data to any analytics platform - only send meaningless IDs that you can join up later.

Q: How long will users remain logged in before needing to log in again
A: This is up to your back end system. If you return a token as a response to your sign in call, you can expire this token whenever you like. We recommend users remain logged into for a long time (forever!) to make the app experience better.

Q: Can I limit how many devices can have concurrent access.
A: Yes, but this needs to be done by your authentication system. We will send the unique device ID to your system if needed, but it is up to your system to expire old tokens or not grant access to new tokens if needed. If you provide a logout method, we can call this so your system can free up old devices.

Q: Will active users only have access to certain content, or will they get access to everything?
A: We support both models, and this will be something we discuss early in the setup. We call the model where an active user gets everything Access Based Model (for example Netflix or Spotify) and the model where they'll only get certain editions the Edition Based Model (traditional print publishing). We can also support things like grant grace issues or grace periods. There is more detail in our authentication in Bolt doc.

Q: How do I stop attacks that hit the Pugpig endpoints and are then proxied to our backend.
A: Ideally if you have the PKCE flow in place, then the login calls are direct to your system and you can protect them as normal. However, we do also send the original requesting IP in the X-Forward-For header which may be useful too.