Skip to main content

 

Documentation & User Guides | FotoWare

Get started with OAuth

Read this first

Eventually, all applications provided by FotoWare will be using OAuth 2.0 to connect to FotoWeb. We encourage migrating existing third-party integrations to OAuth 2.0 for improved user experience and security. Non-OAuth authorization mechanisms from older versions of FotoWeb may be deprecated or disabled by default (with options to enable them).

Documentation of the legacy, non-OAuth, authorization methods can be found here:

OAuth 2.0 also replaces the legacy mechanisms for authorizing FotoWeb widgets embedded in third-party web applications.
Widget documentation pending completion.

IMPORTANT: OAuth requires user interaction and authorization by individual users.
Integrations that don't involve user interaction or that require full administrator access to resources in FotoWeb (such as typical “server-to-server integrations” or “automation integrations”) cannot use OAuth and should use the mechanisms described at API Authentication

Overview

Before an application can access private resources or make changes to information in FotoWeb, it needs to obtain authorization. The preferred way to authorize applications in FotoWeb is OAuth 2.0.

The OAuth 2.0 protocol is an industry standard for authorizing an application to access a service on behalf of a user, where

  • The service is a FotoWeb site or tenant.
  • The application is a web site, web app or native desktop or mobile app made by either FotoWare or a third party.
  • The user is a user registered on the FotoWeb site.

If you are not familiar with OAuth 2.0, then we recommend reading the following introduction: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2.

OAuth 2.0 uses the terms "client", "resource server" and "resource owner". This documentation uses the more intuitive terms applicationservice and user. FotoWeb has the role of the resource server as well as the authorization server.

The OAuth 2.0 standard is documented in RFC 6749. You can use it for reference, but you do not need to read it entirely to be able to use OAuth with FotoWeb.

Once authorized, the application will be holding an access token, which enables it to access resources that the user is authorized to access and perform actions that the user is authorized to perform, or a subset of the former. All actions are performed on the user's behalf.

For example, an application which obtained authorization from user "Bob" can access all archives that "Bob" has permission to access.

If the application creates an album, then the album will be owned by "Bob", and "Bob" will be able to access it in the regular FotoWeb user interface as well.

Access tokens are valid for a short time only, so a stolen access token is of limited use to an attacker. Applications can optionally remain authorized for a longer time by using refresh tokens.

Login and authorization are done interactively using the standard web browser on the platform the application runs on (e.g., Windows, iOS or Android). Authorization is given with the user's informed consent. Users authenticate themselves with FotoWeb using the regular FotoWeb login interface.

This allows users to log in with external authentication providers, such as Azure AD, SAML or Windows Active Directory.

It also ensures that users only ever give their FotoWeb credentials (username and password) to FotoWeb itself, rather than a third party application, which makes it easier to distinguish legit and fraudulent applications and defeat "phishing" attempts, and eliminates the need for (insecurely) storing user passwords in third-party applications.

Only previously registered applications, as well as standard applications provided by FotoWare can use OAuth 2.0 to connect with FotoWeb. This and other mechanisms, such as HTTPS, prevent malicious applications from accessing the data of FotoWeb users.

The application can be of one of the following types:

  • web application hosted on some website, e.g., https://yourapplication.com/, or a web API.
  • native application, such as a Windows desktop application installed on a user's PC or an app installed on a mobile device from an app store.
  • single-page application consisting of static HTML and JavaScript and using embeddable FotoWeb widgets, such as the selection widget.

Getting Started

Example code for using OAuth in a web-based (ASP.NET MVC) application can be found here:

FotoWeb OAuth Example Code (Git Repository)

The application is also hosted publicly, and ready for testing with any FotoWeb server, provided that it is accessible on the public internet:

Try It!

We recommend looking at the example application to get an idea of what OAuth authorization looks like from the user's perspective. This may be helpful in understanding the technical information below.

While the example code is complete and suitable for production, we still strongly recommend reading this documentation for understanding OAuth in FotoWeb. The sections about application registration and access tokens are essential. After that, we recommend reading the section about authorization for the type of application you are planning to develop (e.g., native or web application).

  • Was this article helpful?