Scopes are a way to limit what an application is allowed to do on behalf of a user, given a specific access token. You have probably seen this concept when logging in using Facebook, Google, Twitter etc. or when installing apps on your phone. “This application needs access to view your profile and contacts, allow or deny.”.
In aID we have defined a set of scopes that can be requested during authorization. This set will limit what the third party application is allowed to do with the access token resulting from the authorization.
For example, if the authorization request lists id+name+email, the application can ask aID for id+name+email, but will not receive the user’s phone number, and can’t see what the user has access to. When trying to use an endpoint that requires the access scope, an error response will be given telling the application that the access token has insufficient scope.
Currently implemented scopes
These are the scopes currently implemented in aID:
Title
Title
Label
Description
uuid
The unique identifier of the user in aID. Needed for linking application specific data to a specific aID user.
id
The primary key of the user in the aID database. Needed for linking application specific data to a specific aID user using legacy systems.
name
The full name of the user.
avatar
The user’s profile picture, or alternative picture used to represent the user.
email
The user’s email address.
phone
The user’s mobile phone number.
birth_date
The user’s birth date.
tracking_key
A tracking key that is used to anonymously track the user’s behavior. Needed for integration with statistics systems, but should never be saved in the application.
two_factor_enabled
Whether the user has two factor auth enabled or not.
access
Needed for services that checks a user’s access to a publication.
external_accounts
Needed to see which external accounts are connected to the user’s aID, like Facebook account.
privacy_preferences
Needed to check a user’s privacy preferences.
groups
Needed to get a list of groups a user is a member of, including user UUID’s of other members of said groups.
openid
Special scope defined in OpenID Connect used to trigger OpenID token in response from authorization.
The default scopes are: uuid, name, avatar.
If no scopes are requested during authorization, the default scopes will be used.
How to use scopes
Unless the application only needs the default scope, the application needs a scope strategy. As a developer of the application, you need to think about scopes in three of the steps through the process:
.1When requesting a client_id, you specify the scope (See prerequsites). This scope might be used to limit the scope the application is allowed to request later.
.2When sending the user to the authorization endpoint (See authorization), the scope needed by the application must be specified. This scope can not include scopes not listed in 1, or authorization will fail. All created access tokens will be limited by the scope requested when the access token was created. (ie. you can’t widen the scopes of already created access tokens by changing your application code).
.3When your application calls an endpoint, the endpoint might respond with an insufficient_scope error. When this happens, you need to call the authorization endpoint again to widen the scope (which the user will have to approve). See the OAuth endpoint errors page for details.
Once the access token has been created, aID code takes care of checking the scope when your application tries to access various endpoints.
Considerations
Unless your application is pre approved (see details), the user will be presented with a list of humanly readable explanations for each of the scopes you request when he is sent to the authorization endpoint. If the list is very long, it might scare the user.
If the list is too short, you will need to widen it later, so the user will see this screen more than once. This might annoy the user.
The dialogue will look something like this:
Add a caption...
The trick is to get the scope just right the first time. But consider what your application actually needs, don’t just ask for everything.