aID for third parties
Author: HeHenning Haaland Kulander
Congratulations! You’ve found the documentation for how to integrate your service with aID!
Introduction
This is the entry point for documentation needed to integrate with aID as a third party. The goal is to make it easy for third parties to integrate with aID without lots of guidance and tailoring from aID developers.
The document is currently at a very early stage. Errors and shortcomings might be numerous, please tell us if you find any. The easiest way to tell us is by email to
The integration for third parties is based on OAuth 2.0 and web services returning JSON data using the JSON API format. If you have ever integrated with Facebook, Google, Twitter etc, it should be quite straight forward to integrate with aID as well. If not, it’s probably a bug, so please tell us!
What is aID
aID is an identity provider developed by and for the Norwegian media group Amedia. More than 70 local Norwegian newspapers are currently using this service for access to articles reserved for subscribers, epapers and maintaining subscriptions.
One of aID’s goals is to make it easy for the users of Amedia’s newspapers by allowing them to use a single identity across all services the newspaper provide, and also across all Amedia newspapers. If you read this, you are probably providing a service for one or more of these newspapers, and need user data without forcing the user to create yet another account to log in with.
A common misconception is that aID is about access to reserved content. The misconception probably derives from the fact that this was the first use case for aID. But at its core, aID is just an identity, and the services needed to authenticate as this identity. An aID user does not need to be a subscriber. That said, providing access to reserved content is one of the most important services aID currently provide. aID integrates with the newspaper’s subscription system to figure out if a user has a subscription, or by some other means should have access to the reserved content on a given publication.
Publications
aID, and most other software developed by Amedia Utvikling, is primarily developed for Amedia’s publications, and other publications that pay Amedia Utvikling for software hosting. The publications have for this reason a special role in aID.
aID was made to work as a single application/installation for all our publications. In other words: There’s not one aID for one publication, and another for a different publication. They all share the same installation. But at the same time, it’s important that the users feel at home when logging in to the newspaper, buying access, viewing overlays on articles etc.
For login purposes, we have a slightly different look for the login dialogues for publications than we have for aID login without a publication (which is not much used by users in practice). The difference is that the publications header is shown at the top of the page, and the texts in the interfaced is translated to the newspaper’s language (Bokmål/Nynorsk). You can see examples here (Remember to log out first):
- Without publication: https://www.aid.no/aid/logg_inn/
- With publication ( www.nordlys.no ): https://www.aid.no/aid/logg_inn/www.nordlys.no
When integrating with aID, you need to decide if you want login for your application to have the aID look or the look of a specific publication. OAuth doesn’t specify how to solve this, so it has been solved by using separate endpoints (described here ). The only difference is the look and language, but that can make a huge difference for the user. But please make sure you don’t use the skin of a different publication than the publication the user is currently visiting.
Login with publication header
Login with aID header
Integrating as an OAuth 2.0 client
Before you begin, it’s really useful to have some basic understanding of how OAuth 2.0 works. We recommend these sources for information:
- To the point tutorial explaining the basics about OAuth 2.0
- Getting Started with Auth 2.0 - The O’Reilly book
- The OAuth 2.0 specification, for all the gory details
Before you dive in to these sources, it’s useful to know that you will be the Client, aID is the provider. aID only supports the authorization grant type called “Authorization Code Grant”. The goal of the OAuth 2.0 stuff is to get an access token that lets you as a client act on behalf of a user when calling aID web services. OAuth 2.0 also describe a standardized way of providing this token to web services.
The access token is a secret that is shared between you as a client and aID. If this secret is known to other parties (for examples other apps running on the user’s device), they can steal it and also use it for accessing aID web services for getting information about the user. It’s your responsibility to make sure that this won’t happen with the access tokens provided to you.
The details of using Oauth 2.0 with aID can be found here:
- Prerequisites - What you need to do before starting to code
- Scopes - Limiting the information the application gets access to
- Access roles - Limiting which applications have access to use a service
- Authorization - How to get the access token
- Signle signon/signout - How to integrate seemlesly with the user’s aID session
- Using OAuth-enabled endpoints - How to use the access token
- Signed requests - How to use requests requiring a secure signature
- Available services - What to use the access token for
- Service errors - What could possibly go wrong?
- Logging out - How to delete the access token
What happens when tings start failing?
Modern web applications depend on lots of infrastructure like network, databases, caches etc. in order to work as designed. It’s always a goal to have redundancy in all parts of the system, but from time to time something will happen that no one has anticipated and the system will fail.
The consequence of failure is usually that the user is unable to read premium content. Amedias last line of defence in these situations is something we call Emergency Mode. When in Emergency mode, we try to give all users, logged in or not, access to any content. It’s more important to have happy customers than to protect our content.
It’s possible for third parties to detect when we are in emergency mode and provide the same behaviour for users on third party sites. Read more about this in Emergency Mode