Authorization





Introduction


This is where the fun stuff begins. Down to the actual coding. We assume that you know the basic about OAuth 2.0 by this point. If not, this is the time to read up on it. But it’s not as hard as some would make you believe.

The goal here is simple: Get an Access Token.

Once we have the access token, this token should be stored securely on a server so it can be used in later requests (unless you only need to make one single request to get an email address or something). The access token is used in all subsequent requests for webservice endpoints when acting on behalf of the user. More about this  later⁠ .


Roles

Title
Title
Name
Description
Resource Owner
This is the aID user. He might be logged in to aID, and your application want his data.
Resource Server
This is the aID server containing the data, or the endpoints to the webservices providing the data to be more precise.
Client Application
This is your application. The one you are about to code.
Authorization Server
This is the OAuth 2.0 server in aID. The one that will give you the access token.


Artifacts

Title
Title
Name
Description
Access Token
This is the token that can be used to perform requests on behalf of Resource Owner to Resource Server in order to get data for Client Application
Authorization Code
This is the code sent as a parameter to redirect_uri that Client Application must send to Authorization Server in order to get an Access Token
redirect_uri
Pre configured URI the Authorization Server will send user to after Authorization endpoint has finished
client_id
Pre configured ID of the Client Application. Provided to Authorization endpoint so Authorization Server can know which application requests the authorization
client_secret
Pre configured password for the Client Application. Provided to Token endpoint so Authorization Server can be sure that no evil man in the middle has picked up the Authorization Code and is trying to steal the access token.
state
Optional unique parameter Client Application can send to Authorization endpoint, that will be sent unaltered to the redirect_uri after Authorization. Can be used to keep client state, and also to prevent against attacks ( See details here ).
Publication
The publication the user is using, if applicable. Identified by www_domain (eg.  www.nordlys.no )


Brief overview of the process



https://slite.com/api/files/BGgqv1VG0/2d7da955-da15-4bb4-b189-d936566055b5?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoiVG5nXzBvY0xPZiIsImlhdCI6MTczMjM3MzQyOSwiaXNzIjoiaHR0cHM6Ly9zbGl0ZS5jb20iLCJqdGkiOiIzVWppTzRqTlBFTk1xYSIsImV4cCI6MTczNDk2NTQyOX0.lftZULOjRIt04lgUPGOnTE6cg5JhK99NE_TUV-BRgpA


    .1User (Resource owner) clicks on link that takes him to a page in Client Application.
    .2Client Application needs user.id and user.name, has no access token, so responds with redirect to *Authorization endpoint** in Authorization Server
    .3Authorization Server checks if user is logged in to aID, he’s not (if he was, we would skip 4 and respond as if this was 5), so response is redirect to aID login page.
    .4User logs in to aID (standard login on  www.aid.no ) and is redirected back to Authorization endpoint in Authorization Server.
    .5Authorization Server checks if user is logged in to aID, he is. Authorization server checks if Client Application is Pre Approved (let’s assume it’s not), and checks if the URL contains a list of approved scopes. It does not, so response is redirect to aID approve scopes page.
    .6User grants scope on aID and is redirected back to Authorization endpoint in Authorization Server, with URL containing a list of approved scopes.
    .7Authorization Server checks if user is logged in to aID, he is. Authorization server checks if Client Application is Pre Approved (let’s assume it’s not), and checks if the URL contains a list of approved scopes. Now everything checks out OK, so Authorization server creates an Authorization Code and stores this for the user in a database. User is now redirected back to redirect_uri with a parameter called code. The value for code is the Authorization Code
    .8Client Application responds to redirect_uri request from user’s browser and reads the code. It then sends a request to Token endpoint in Authorization server and provides client_id, client_secret, redirect_uri and Authorization code (code parameter).
    .9Token endpoint in Authorization server Verifies the Authorization code and checks that it’s registered to the Client Application and that the client_secret and redirect_uri matches with the associated Client Application. If everything matches, it creates an access token and sends this to Client Application as a JSON response.
    .10Client Application reads the “access_token”. It now has the Access Token and can call Resource Server on behalf of the Resource Owner.


User dialogues


In step 4, the user will see this dialogue, and will continue by clicking one of these buttons: 


https://slite.com/api/files/7cPe2VRLa/image.png?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoiVG5nXzBvY0xPZiIsImlhdCI6MTczMjM3MzQyOSwiaXNzIjoiaHR0cHM6Ly9zbGl0ZS5jb20iLCJqdGkiOiIzVWppTzRqTlBFTk1xYSIsImV4cCI6MTczNDk2NTQyOX0.lftZULOjRIt04lgUPGOnTE6cg5JhK99NE_TUV-BRgpA
In step 6, the user will see this dialogue, and will continue by clicking on the grant button:
 

https://slite.com/api/files/7pC3uBz4kJ/image.png?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoiVG5nXzBvY0xPZiIsImlhdCI6MTczMjM3MzQyOSwiaXNzIjoiaHR0cHM6Ly9zbGl0ZS5jb20iLCJqdGkiOiIzVWppTzRqTlBFTk1xYSIsImV4cCI6MTczNDk2NTQyOX0.lftZULOjRIt04lgUPGOnTE6cg5JhK99NE_TUV-BRgpA

Single signon / signoff


Granting access_token requires that the user has an active aID session. If he hasn’t, he will be sent to the login page in order to aquire one (as explained in step 3 to 5 above). When authorization is performed, a link is saved between the session, the grant_token and subsequently the access_token. When the user logs out, all grant_tokens and access_tokens are invalidated. If an access_token is revoked by an application, the reverse happens and the session is invalidated, which in effect logs out the user of aID.

If you need to be informed about token invalidation, please inform us, and we can set up an endpoint we will do an HTTP delete on when one of your application’s access_tokens is revoked.

If you need to check if the user is logged in to aID, you can do what we call a stealthy authorization (and OpenID calls prompt=none). Stealth mode works by adding a parameter called stealth_mode with the value true to the authorization request (prompt=none will also work, for compatibility). If this parameter is present, the OAuth service will skip straight from step 3 above to step 8 if the user is not logged in. If he is, it will work the same as without. The effect is that the user will never see any user interface before the browser is directed back to redirect_uri.

If stealthy login fails, stealth_login_status=failed will be appended to the redirect_uri. When this parameter is present, the calling application will know that the user is not currently logged in to aID in the current browser session. The application can show a login-button that will log the user in using a non stealthy OAuth approach.

See more about single signon  here⁠ 


Authorization endpoint - Getting the authorization grant code


So this is where the Client Application sends the user when it wants an Access Token on behalf of the user. It’s not a web service endpoint, but a URL the user is redirected to through the web browser.

URLs:
https://www.aid.no/oauth/authorize/<publication domain (eg www.nordlys.no)>
https://www.aid.no/oauth/authorize

You probably want to use the first one, since this will provide the user with a login screen and approve screen skinned for the specific application. So the user experience is that the user never leaves the site. If your application is not publication specific, use the second endpoint and the user will get the standard aID skin. Both versions are identical except from the skinning.

Parameters

Title
Title
Name
Description
client_id
client_id provided by aID when registering the application
response_type
The OAuth 2.0 grant type to use. Only Auhorization Grant Code is enabled, so code is the only value that will work here (response_type=code)
redirect_uri
The redirect_uri provided to aID when registering the application
scope
List of scopes needed by the Client Application, separated by + (eg. scope=id+name+email)
stealth_mode
‘true’ if you want to try an auto login without showing dialogue to user if user is not logged in. See more above
custom_action
Optional custom action instead of standard aID login if user is not logged in.
cfv_
Custom field values that will be sent to custom action.
Remember, there’s a contract between the Client Application and the Authorization Server. This is set up when aID receives the request to register a new application. If redirect_uri, client_id or scope doesn’t match what was agreed upon at registration, this endpoint will fail. For security reasons, it’s often difficult to know exactly what was wrong.

On its way from the Authorization Endpoint to the redirect_uri, the user can be redirected through a number of pages. This is out of the control of the Client Application. A Normal flow will be like this:

    .1Authorization endpoint
    .2Login page on  www.aid.no  (which in reality consists of a number of pages, and might even do it’s own OAuth login through Facebook)
    .3Scope approval page (where user approves access to requested scope)
    .4Authorization endpoint
    .5redirect_uri


Example


https://www.aid.no/oauth/authorize/www.glomdalen.no?client_id=c4feb4b3&response_type=code&redirect_uri=https%3A%2F%2Fwww.example.com%2Faid_login&scope=id+name+email&state=denial

In this example, we assume that we have the following Client Application:
Title
Title
Field
Value
client_id
c4feb4b3 (Normally this ID is a lot longer)
client_secret
1c3b00d4 (Normally this password is a lot longer)
redirect_uri
 https://www.example.com/aid_login 
scope
id name email

If everything goes according to plan, the user will end up here:
https://www.example.com/aid_login?code=d34db33f&state=denial

This URL has two parameters:
Title
Title
Parameter
Description
code
The Authorization Code needed for Client Application to get the Access Token
state
The state parameter provided by Client Application to the Authorization Endpoint, unaltered. If it’s changed, something is wrong!
The example application lives on www.example.com, so this application now needs to use the code d34db33f to get an Access Token, and it should also verify that the state is sane.


Custom actions


Some third party applications might want a more custom user interface in the application end, ie. before sending the user to aID. Some examples could be to have Facebook, Google or Create aID buttons directly in the application user interface. This can be accomplished by using custom actions.

Currently these actions are available:
Title
Title
Action
Description
login
This is the default login with buttons to all the actions below
login_with_password
Starts on the standard login dialogue with username (phone) and password fields
login_with_facebook
Starts on login with Facebook. (Note: User will have to connect Facebook to aID or create aID)
login_with_google
Starts login with Google. (Note: User will have to connect Google to aID or create aID)
create_aid
Starts on the create aID dialogue
Considerations:
  • If the user is logged in to aID, the user will never be sent to the custom action, standard OAuth logic applies.
  • It might be confusing for a user of a third party application to understand why he suddenly has to create an aID when he tried to login with Google or Facebook.
  • Google does not allow OAuth login in webviews (read  announcement here ). The user will get an error when clicking the login with Google buttion if the button is not hidden from applications using webviews.


Custom field values


If the third party application knows what the user wants to enter in the custom action page, the application can use custom field values to pre fill the form. For example if the user has performed a purchase in the third party application, and now wants to create a new aID, the application can send name, phone, email and birth date used in the purchase so the user won’t have to enter it again when creating an aID.

Custom field values are currently only supported for the create_aid custom action.

Currently these fields are available:
Title
Title
Title
Parameter name
Field
Description
cfv_name
name
User’s full name
cfv_phone
phone
User’s mobile phone number
cfv_email
email
User’s email address
cfv_birth_date
birth_date
User’s birth date
The application does not need to provide values for all fields, the missing fields will remain blank.

Example:
https://www.aid.no/oauth/authorize/www.glomdalen.no?client_id=c4feb4b3&response_type=code&redirect_uri=https%3A%2F%2Fwww.example.com%2Faid_login&scope=id+name+email&state=denial&custom_action=create_aid&cfv_name=Test+Testesen&cfv_phone=12341234


Token endpoint - Getting the access token


The token endpoint is a web service endpoint that responds with JSON data.

URL:
https://www.aid.no/oauth/token

To get the Access token the Client Application needs to perform a POST request to this URL, and provide a set of parameters. The request should set Content-Type to multipart/form-data.

Authorization for this endpoint is documented in detail in the OAuth2 spec  here . The application authenticates itself by encoding the the applications client_id andclient_secret as username and password in a  Basic  Authorization header.

An alternative to using the Authorization header is to set client_id and client_secret as request parameters or as a part of the posted data. This is not recommended, as it can lead to secrets being leaked to logs etc. Use headers when possible.


Form fields

Title
Title
Name
Description
grant_type
The OAuth 2.0 grant type to use. Only Auhorization Grant Code is enabled, so authorization_code is the only value that will work here (grant_type=authorization_code)
code
The code provided as parameter to redirect_uri after return from Authorization Endpoint
redirect_uri
The redirect_uri provided to aID when registering the application
The response will be a JSON object. The important field here is the access_token, which is the very Access Token we have fought so bravely to retrieve. But here is a full description:
Title
Title
Attribute
Description
access_token
This is the Access Token we are looking for
token_type
Set to bearer, to indicate that this is a bearer token, for implementations supporting multiple types
scope
The scope the Access Token is valid for. Should be the same as the one requested by Client Application, or default scope is no scope was requested.
created_at
Timestamp when the token was created.
expires_in
If present, how many seconds until this access token is no longer valid
id_token
OpenID Connect JWT if OIDC mode was requested using the openid scope to authorization endpoint


Example


Given the full redirect_uri in the example above for Authorization Endpoint, we could call the Token Endpoint using curl like this:

curl -H 'Authorization: Basic YzRmZWI0YjM6MWMzYjAwZDQ=' -F grant_type=authorization_code -F code=d34db33f -F redirect_uri=https://www.example.com/aid_login -X POST https://www.aid.no/oauth/token


The service should return a token like this:

{    
  "access_token": "d4bbad00",    
  "token_type": "bearer",    
  "scope": "id name email",    
  "created_at":1422988263
}

And there we have it! The Access Token is d4bbad00. We can now provide this to all aID OAuth enabled endpoints as described  here⁠ , and we should be able to get the user’s ID, email and name.

The difficult part is now done. Using the endpoints is a lot simpler! Promise!