SmartCommunity platform uses OAuth2.0 protocol for the resource access authorization and external identity providers (e.g., Shibboleth of FBK, Shibboleth of University of Trento, Google OpenID) for the user authentication. SmartCommunity supports variety of scenarios including JavaScript, web server, and installed app.

Here we provide an overview of overall procedure and of the different access methods.

The OAuth 2.0 protocols imposes the following common pattern to access protected SmartCommunity resources:

The application that wants to access a protected resource must be registered through the Developer Console. With this the developer obtains the necessary attribute values (e.g. client_id, client_secret/client_secret_mobile, redirect_uri, etc.). These values are necessary to perform the user authorization and to obtain the corresponding access_token values, with which the access to the resources is granted.

Besides, the application should explicitly state during the registration which resources it would like to access.

More information about application registration can be found here.

Before an application can access a SmartCommunity resource, it must obtain an access token. Two types of tokens are supported: the user token that grants access to the user resources or to some generic resources on behalf of the user and the client token that grants access to the client application resources (used in the server to server flows without involving a user). The set of resources permitted by an access token is controlled during the access token request through a parameter called 'scope'.

According to OAuth2.0, to obtain the token different approaches (flows in OAuth2.0 terminology) may be used. They all depend on the application type and usage scenario.

When the application has to obtain the user token, the latter should first authenticate (sign in) to the SmartCommunity and then authorize the permissions the application requires. If the user grants the requested permissions, the application will receive an access token directly (in case of implicit flow) or an authorization code (used to obtain an access token, this is the case of authorization code flow). If the user does not grant permissions, an error is returned. For the security considerations, it is strongly encouraged to use authorization code flow wherever possible, even if it requires extra effort for the developer.

In case of client token request, the calling application should provide the values for the client_secret and client_id.

Once an access token is obtained, the application may issue requests to the protected resources. Note that only the resources for which the access has been request and granted may be accessed in this way. The request to non-authorized resource will result in an error. Access tokens are sent in the HTTP Authorization header.

Access tokens have a limited lifetime and, in some cases, an application may need access the resource beyond the lifetime of a single access token. In this case, the application may exploit the refresh token that allows your application to obtain new access tokens.

When needed, it is possible to revoke the token thus invalidating its current value. If the access token is associated with the refresh token, also the refresh token will be revoked.

Below we present different usage scenarios of the Authorization and Authentication.

The SmartCommunity authentication system can be used to outsource user authentication and profile acquisition to SmartCommunity.

The login sequence starts by redirecting the browser to a SmartCommunity URL with a set of query string parameters. More specifically, the URL and parameters correspond to requesting a access_token with the scope of only reading the basic profile of the current user. The SmartCommunity then accepts and validates the user credentials, obtaining consent to release basic profile information, as well as returning an OAuth2.0 access token to the application.

As a result, the access token is issued and it is possible to request the current user profile from the Basic Profile Service thus obtaining information about the user (e.g., name, surname, userId). This info can be used during user registration.

For more information, see the Login documentation.

This is a scenario, where a Web application wants to access user resources server-side. To do this, the Web application should obtain the access token (and possibly the refresh token) and store it for future calls.

The sequence begins by redirecting a browser (popup, or full-page if needed) to a SmartCommunity Authorization URL with a set of parameters to specify, e.g., access scope. Like other scenarios, SmartCommunity Authorization Server handles the user authentication, but the result of the sequence is an authorization code. After receiving the authorization code, another request should be made the application can exchange the code for an access token and a refresh token.

Where possible, this method should be preferred over the flow demonstrated in Client-side Applications scenario (i.e., implicit flow). For more information, see the Authorization Code Flow documentation.

The JavaScript applications may perform call directly to the SmartCommunity resources. Like the other scenarios, this one obtains the access token by redirecting a browser to a Authorization URL. SmartCommunity Authorization Server handles the user authentication and access authorization and emits an access token. The access token is then included in a resource API request.

For more information, see the Implicit Flow documentation.

The SmartCommunity Authorization Server supports mobile applications. These applications, in general, cannot keep secrets. The sequence is similar to the one shown in the Web Server section, but there are three exceptions:

• a different value for the redirect_uri parameter has to be specified.
• The client_id and client_secret_mobile obtained during registration are embedded in the source code of your application. In this context, the client_secret_mobile is obviously not treated as a secret.
• The authorization code (or token) is returned to your application differently.

This sequence begins by redirecting an embedded browser to the Authorization URL followed by authentication and access grant. The result of the sequence is an authorization code returned in the redirect URL.

After the application has received the access and refresh tokens, it may store the refresh token for future use, and use the access token to access a resources. Once the access token expires, the application obtains a new one with the refresh token.

For more information, see the Mobile Application documentation.

A range of SmartCommunity services act on behalf of an application and do not access user information. This refers to management of app file storage accounts, community management, communicator app profile registration, aggregated information access, etc.

To access such services, the app should prove its own identity. SmartCommunity Authorization Server supports these types of applications through the Client Credentials Flow.

To perform access, the application itself should obtain client access token. The token is issued to an application on the basis of its client id and secret.

For more information, see the Client Credentials Flow documentation.

SmartCommunity provides a set of client libraries to facilitate the management of the authorization and authentication:

• SmartCommunity AAC Client Library for Java
• SmartCommunity AAC Client Library for Android

~~DISQUS~~