Application registration using OAuth 2.0

01. April 2025

Table of Contents

Application registration Redirection endpoints HTTP(S) Web URLs Private-use URI schemes HTTP loopback URLs What's next?

Application registration

FotoWeb only allows registered applications to be authorized using OAuth 2.0. Applications are registered by the FotoWeb administrator in the site configuration interface.

Some applications provided by Fotoware, such as FotoWeb Desktop and the FotoWeb mobile apps, may use OAuth 2.0 as well. There is no action required to register these applications.

From the Tools menu (cogwheel icon), go to Site Configuration > Integrations > Applications.
Select Add application.
Select a value from the Type drop-down list.

Native / mobile - for native desktop applications (Windows, Mac, ...), mobile applications (Android, iOS, ...), and single-page applications or applications using only the FotoWeb widgets.
Web App / API - for web applications with a back-end (server) component or web APIs
Non-interactive/script - for non-interactive applications.

For security reasons, we strongly recommend ALWAYS selecting the proper application type, even if it may seem that one type "works" for another actual type of application. For example, authorization for web applications is slightly easier to implement, but it is unsuitable for native applications, because a native application is a publicly available client which cannot keep the client secret secure from users reverse-engineering the binary of the application.

Web applications that are distributed as software packages to be installed on premises must allow the client secret to be configurable rather than hard-coded, so each installation can use its own secret without exposing it to other customers.

Furthermore, an application has the following properties:

A client ID that uniquely identifies the client and is created upon application registration.
One or more redirection endpoint URIs, which are used by the authorization protocol and which must be controlled by the application.
For web applications only: A client secret, used for client authentication.

The client secret is shown to the administrator only once when it is generated. It cannot be retrieved later. If the client secret is lost, then a new one must be generated.

The client secret MUST NOT be exposed publicly. It must be stored securely in the back-end of the application only. Therefore, native and single-page applications cannot have a client secret and must use other mechanisms to protect the authorization process.

Redirection endpoints

An application must control one or more redirection endpoints to receive and handle HTTP(S) requests from a standard browser. Each redirection endpoint URI must be registered and be of one of the following formats:

A standard HTTP or HTTPS web URL
An HTTP loopback URL
A URI with a private-use scheme

Common rules for all types of URIs are:

MUST NOT contain a fragment part (#...)
MUST NOT contain a query part (?...)
MUST NOT be identical to another redirect URI of the same or another registered application

HTTP(S) Web URLs

This type of redirection URI is typically used for web applications, but it may also be used for native applications on some mobile platforms that support claimed "HTTPS" URIs (i.e., URLs that are automatically opened in an app rather than the default browser). Claimed "HTTPS" URIs are also the recommended approach for native applications on platforms where they are supported.

Example:

https://apps.acme.org/oauth2redirect/example-provider

The following additional rules apply for HTTP(S) web URLs:

MUST be absolute (i.e., contain both the scheme, https:// or http://, AND a host name)

MUST not have a common prefix with the FotoWeb site URL with ANY protocol.

Example: If the site URL is https://abc.fotoware.cloud, then the following redirect URIs are all invalid:

http://abc.fotoware.cloud
https://abc.fotoware.cloud
gibberish://abc.fotoware.cloud

The host name MUST be the domain name you own and manage.

For security reasons, it is strongly recommended to use HTTPS redirection URLs only. The application SHOULD have a valid CA certificate. Although OAuth 2.0 provides additional measures for preventing interception of authorization codes and access tokens, HTTPS and host verification helps ensure that the endpoint URI is controlled by the application.

Private-use URI schemes

Native applications may register private-use URI schemes to make the OS automatically pass requests using these URIs to the application. This is an alternative to claimed "HTTPS" URIs on systems where they are not supported, such as most desktop systems (Windows, Mac, ...).

Example:

com.example.app:/oauth2redirect/example-provider

where the part after the slash is an arbitrary URL path using the same syntax as regular URLs.

The scheme MUST be a reversed name of a domain that actually exists and is controlled by the owner of the app. FotoWeb does not technically enforce this rule. However, policies of some app stores may require this and allow vendors to petition apps using their domain names and remove offending apps from the app store.

For example, we could use com.fotoware.XXX for our own apps. A subdomain XXX doesn't really need to exist, because we control everything under fotoware.com.

HTTP loopback URLs

Native applications may listen on the loopback interface of the device they are running on. This is an alternative on platforms that do not support claimed "HTTPS" URIs or private-use URI schemes. To support both IPv4 and IPv6 interfaces, an application SHOULD always register redirection endpoint URLs for both protocols:

http://127.0.0.1:7777/oauth2redirect/example-provider
http://[::1]:7777/oauth2redirect/example-provider

The port can be any port on which the application can listen. However, ports 8800-8899 are reserved for Fotoware applications and MUST NOT be used.

Using localhost as the host name is supported but not recommended, for security reasons.

During authorization, the application MUST send the redirect_uri parameter using the correct redirection URI for the loopback interface (IPv4 or IPv6) it is listening on.

What's next?

Next, you can learn how to obtain an access token in your application. The method for doing this depends on the type of application you are building.

Application registration using OAuth 2.0