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:
- For the FotoWeb API: https://learn.fotoware.com/02_FotoWeb_8.0/Legacy_API's/API_Authentication
- For the ArchiveAgent API: https://learn.fotoware.com/02_FotoWeb_8.0/Legacy_API's/The_FotoWeb_Archive_Agent_API_(Legacy)/User_authentication_with_the_Archive_Agent_API
OAuth 2.0 also replaces the legacy mechanisms for authorizing FotoWeb widgets embedded in third-party web applications.
Overview
Before an application can access private resources or change information in FotoWeb, it needs 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 website, 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 this 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 application, service 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 hold 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 only valid for a short time, 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 application's platform (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 Microsoft Entra ID, 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 legitimate and fraudulent applications and defeat phishing attempts. It also 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:
- A web application hosted on some website, e.g.,
https://yourapplication.com/
, or a web API. - A 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.
- A 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:
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).