OAuth 2.0 Authentication

With OAuth authentication mechanism you can use API methods without keeping user's credentials (username/password) in an external application. To learn more about OAuth, please visit the official website http://oauth.net/2/

To get an access_token you can proceed in different ways:

• Using the OAuth authorization dialog flow (for Web Applications)
• Using the Native App access_token request flow (for native/desktop/smartphone/tablet applications)
• Requesting an access_token directly from your account (for instance, using the API Explorer)

Register your OAuth 2.0 client application

In order to setup your OAuth access, you have to register your Application. You can do it by creating a Digital Certificate of type "OAuth 2.0 Client Application" using your control panel.

When you create the Digital Client you have to enter:

• a client_id: this is the key value that your application will use to identify itself during OAuth protocol requests
• a client_secret: this is a secret that you need to store in a secure way inside your application. This is optional for the javascript flow
• a redirect_uri: this is the URL of the page which will receive OAuth data (the 'code' and 'state' parameter). This is optional for the username/password flow
• an Application Name: this is the Name of the Application that will be shown to the user during the Authorization Dialog. This is optional for the username/password flow.

Getting quickly started

Usually, you will get an access token following one of the standard OAuth flows, but if you want to get an acces_token for playing with the API you can proceed in this way:

1. Login on account and access to the menu item "Management" "System" "Digital Certificates"
2. Create a new digital certificate "OAuth 2.0 Client Application" (details of each field can be found here, under "Register your OAuth 2.0 client application").
3. Once you created the certificate, on the same page, you can get the access_token, clicking on the button "Get access token."
4. In the opened page you will find the following data:
   access_token: Access Token
   refresh_token: it has to be used in your application to return the token and updating its validity (for info just always refer to the OAuth 2.0 documentation).
   token expiration: expiration of the validity of the token. Initially, the validity will be set for a few hours. To upgrade the expiration just use the previous refresh_token in your app/site, or simply manually extend the expiration date.

To read these information in the future, you can go to the menu item with the name of your user (top right of the screen) "Profile". In the tab Authorizations account there is the record of access_token used.

It's not necessary to create a new username to use web services only when using OAuth 2.0.

Web Application Flow

In order to get an access_token for your web application, just follow these steps:

1. Redirect the browser to the OAuth Dialog Page (passing account, client_id, scope and state parameters)
2. The user will be prompted to your application the permission to get an access_token.
3. If the user allows the access, then the browser will be redirected to your redirect_uri passing a 'code' parameter and passing back the 'state' parameter
4. If the user denies the access, then the browser will be redirected to your redirect_uri passing an 'error' parameter and passing back the 'state' parameter
5. Once you have got the 'code', do a server-to-server call to the OAuth Token Endpoint passing client_id, client_secret and code parameters
6. If everything looks fine, you will receive the access_token and the refresh_token
7. Now you have the access_token and you can use it for API calls
8. You have to periodically refresh your token using the refresh_token (see Refreshing a token)

Complete Web Application example

Setup parameters

client_id: myapp
client_secret: xxxxx
scope: full
redirect_uri: http://mywebsite.com/mywebapp/auth_callback.php
state: examplestate
account: myaccount
accountwebserver: be-mn1.mag-news.it

Redirect user browser to

https://be-mn1.mag-news.it/be/oauth/dialog?response_type=code&account=myacccount&client_id=myapp&scope=full&redirect_uri=http://mywebsite.com/mywebapp/auth_callback.php&state=examplestate

If the user denies the access, its browser will be redirected to

http://mywebsite.com/mywebapp/auth_callback.php?state=examplestate&error=access_denied

If the user grants the access, its browser will be redirected to

http://mywebsite.com/mywebapp/auth_callback.php?state=examplestate&code=CCCCCCCCCCC&expires_in=3600

Now you have got the 'code', in this example is CCCCCCCCCCC.

Do a server-to-server call to the token endpoint

POST to https://be-mn1.mag-news.it/be/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=myapp&scope=full&code=CCCCCCCCCCC&client_secret=xxxxx&&redirect_uri=http://mywebsite.com/mywebapp/auth_callback.php 

You will receive an application/json encoded response which will look like this:

{
    "access_token":"UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU",
    "refresh_token":"QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ",
    "expires_in":3600,
    "token_type": "Bearer"
}

Username/Password flow

In order to get an access_token for a desktop/native application (such as an Android/iPhone App) you can use the username/password flow.
This flow is not suitable for web applications because it requires the user to enter its username/password credentials outside of the official login page of the platform.

Steps:

1. Ask the user for its credentials, that is account/username/password
2. Do a server-to-server call to the OAuth Token Endpoint passing client_id, client_secret, username and password
3. If everything looks fine, you will receive the access_token and the refresh_token
4. Now you have the access_token and you can use for API calls
5. You have to periodically refresh your token using the refresh_token (see Refreshing a token)

Complete Username/Password example

Setup parameters

client_id: myapp
client_secret: xxxxx
scope: full
account: myaccount
username: myusername
password: TheBestPassword_1234

Do a server-to-server call to the token endpoint

POST to https://be-mn1.mag-news.it/be/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=myapp&scope=full&client_secret=xxxxx&username=myusername@myaccount&password=TheBestPassword_1234

You will receive an application/json encoded response which will look like this:

{
    "access_token":"UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU",
    "refresh_token":"QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ",
    "expires_in":3600,
    "token_type": "Bearer"
}

OAuth scopes

OAuth scope parameters is a specification of a subset of features/resources for which the application is requesting access.

Here are the available scopes:

• full: to access every resource
• loginbackend: to be able to open the control panel (the account user interface), but not to use the API.

Forcing the approval prompt

If the user is actually logged and has already granted an access_token for the requested scope list, the platform will not show the approval prompt dialog.

In order to force the dialog to appear, add the parameter approval_prompt=force to the dialog url.

Revoking an access token

If you want to revoke access to an OAuth 2.0 client application, you can simply log into your account and go to the "My Profile" page, then in the OAuth tab you can delete the relative access_token.

The client application will not be able to use the access_token anymore, neither to refresh it.

The client application will need to follow the authentication flow from the beginning.

Refreshing a token

Normally access_tokens have a limited lifetime, usually it is 1 hour.

If you want to "refresh" an access_token you have to follow these steps:

1. Call the OAuth Token Endpoint passing the client_id, client_secret, refresh_token, scope parameters.
2. If everything looks fine, your access_token lifetime will be refreshed.

Example response:

{
    "access_token":"UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU",
    "refresh_token":"QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ",
    "expires_in":3600,
    "token_type": "Bearer"
} 

To see PHP and Java examples, see refresh token examples.

Getting info about an access_token

You can get info about an access_token by using this endpoint:

https://be-mn1.mag-news.it/be/oauth/tokeninfo?access_token=XXXXXXX

You will get an application/json response that contains these infos:

• access_token: the access_token
• account: account name
• platformCustomerId: account ID
• expires: expires seconds
• userid: account user ID
• scope: granted scopes
• userdescription: name of the user
• userlanguage: user language (Java local id)
• usertimezone: user time zone (Java Timezone id)
• valid: boolean indicating validity
• uiurl: WWW service host
• sftpserver: SFTP service host
• smtpserver: Simply SMTP service host
• apiurl: Web Service host

Logging inside the account user interface programmatically

To login your user to the control panel programmatically, you should have an access_token with scope "full" or at least "login_backend" and then redirect the user to:

https://be-mn1.mag-news.it/be/common/autologin.do?account=ACCONTNAME&access_token=XXXXXXX

If you want to get the user to a specific page, you can add a "page" parameter:

https://be-mn1.mag-news.it/be/common/autologin.do?account=ACCOUNTNAME&access_token=XXXXXXX&page=system:newsletter_edit?idnewsletter=1

In this example, the string system:newsletter_edit?idnewsletter=XXXX should be encoded as an URI component.
This function is particularly useful when you want to launch the web interface from another web application and direct the user on a specific page, which can be a system page or a custom page deployed inside an App.

Registering your client_id automatically

The registration of your client_id (and client_secret) is required in order to follow any of the OAuth 2.0 flows.
In order to leverage the user of your application from this step, you can develop an App and inside the "Setup Handler" you can register your application.