1.3.4. Authentication & authorisation

The terms authentication and authorisation are often used interchangeably, however:

  • Authentication is the process of verifying who a user is,

  • Authorisation is the process of verifying what they have access to.

Access tokens

If the application needs to use any Proximie services, it will need to be authorised, typically with a user’s credentials. When successful, the application is given an access token that it can use to access the services (e.g. make REST API calls).

Proximie uses “Open Authorization”, better known as OAuth 2.0, which is an authorisation standard. OAuth 2.0 works with standard technologies such as HTTP/REST, JSON, etc. and so does not intrinsically demand any unusual APIs or libraries to work with it. For details of the authorisation processes supported by Proximie, see An overview of auth at Proximie.

Depending on the application’s needs, and the type of infrastructure being used (e.g. the main Proximie infrastructure or a private tenant), the appropriate authentication flow may differ. Consequently, the SDK itself does not currently implement APIs directly for authentication (though applications can make use of Proximie utilities such as PxUtility::HttpFetch).

Auth0

Proximie uses Auth0 as its underlying auth provider. Auth0’s documentation is excellent, and provides in-depth details and information about authentication flows etc.

Here is a list of key topics that application writers should find useful:

Token providers

The IAccessTokenProvider interface is used to implement a token provider. It simply promises to return a valid and fresh access token on request.

As mentioned above, it is the application’s decision on what mechanism it uses to obtain the access token, and to handle short-lived token expiry by obtaining a new access token before the existing one expires (and is thus invalid).

An implementation of a IAccessTokenProvider might be:

  • On startup, begin an OAuth authentication flow requiring the user to enter their credentials.

  • On successful authentication, store the access token, and the provided refresh token.

  • Set a timer based on the expiry time returned with the access token.

  • When requested, return the cached access token.

  • When the expiry timer fires, use the refresh token to obtain a new access token. Again record the new token, the new refresh token, and set a new expiry timer.

See the IAccessTokenProvider documentation for more details.