Guide to Android Storage Access Framework

The modern mobile ecosystem is undergoing significant changes changes in security and privacy of user data. One of the key tools that ensures these standards is Storage Access Framework (SAF). This technology provides a standardized interface that allows applications to securely interact with the device's file system and remote storage without having to request full rights to read the entire disk.

Previously, developers often used direct file paths, which created vulnerabilities and conflicts between apps. Now Android strongly recommends using the system file manager to select documents, images and media files. Understanding how SAF works is critical both for users who want to understand application permissions and for software creators.

The introduction of this system changes the way we work with files. Instead of the application scanning the memory itself, the user selects a specific file through a single system interface. This gives complete control over what data the installed software gets access to, minimizing the risks of leakage of personal information.

Architecture and principle of operation of SAF

It is based on a client-server interaction model. The application acts as a client that makes a request to access a document, and the Android system or a third-party document provider acts as a server that provides this access. This architecture allows you to abstract away from the physical location of the file. Storage Access Framework lies the client-server interaction model. The application acts as a client that makes a request to access a document, and the Android system or a third-party document provider acts as a server that provides this access. This architecture allows you to abstract from the physical location of the file.

When you select a file through SAF, the application does not receive a direct path to the file on the file system (for example, /sdcard/Download/file.txt). Instead, it receives a unique URI. This identifier is a temporary or permanent access token that allows you to read or write data without knowing the actual location of the object on the disk.

Support for working with documents is provided by special components called DocumentProvider. By default, the system has a built-in provider that displays files in the internal memory and on the SD card. However, users can install third-party file managers, which are also registered as providers and become available through a single selection interface.

⚠️ Warning: Direct access to file system paths through old methods is gradually being blocked in new versions of Android. Using outdated paths may cause the application to crash or deny access to data.

It is important to note that the system caches permissions. If you once gave an app access to a specific folder via SAF, it can retain this permission for subsequent operations without asking again until you explicitly revoke the permission in system settings.

Instructions for users: how to grant access

For a regular user, interaction with Storage Access Framework occurs when the application requests a file. For example, when you want to attach a document to a letter or upload an avatar to a social network. The system automatically opens a standard file selection window, which is part of SAF.

The process of providing access is intuitive, but has its own characteristics depending on the type of data requested. You can select single files or entire directories. When you select a folder, the application gains access to all attached files, which requires special care.

Consider a typical scenario for working with a file manager or document editor:

• 📂 Click the "Open" or "Import" button in the application interface.
• 📱 In the system window that appears, select the desired storage (Internal memory, Google Drive, SD card).
• 📄 Find and click on the specific file or folder to which you want to give access.
• ✅ Confirm the action by clicking the "Allow" or "Use this folder" button.

Particular attention should be paid to the situation when an application requests access to the entire root directory. In this case, the system will issue a warning that the application will gain control of all files in the selected partition. This is only acceptable for file managers or backups that really need this level of access.

Management of issued permissions is carried out through system settings. You can go to the access rights section at any time and revoke a token from a specific application. After this, the app will lose the ability to read previously selected files until access is granted again.

Technical implementation for developers

For application creators, integration Storage Access Framework requires the use of special Intent requests. The main mechanism is based on launching the file selection activity using the action ACTION_OPEN_DOCUMENT or ACTION_CREATE_DOCUMENT. This allows the system to take control and show the user a secure interface.

The code for initiating the request looks quite simple, but requires correct processing of the results in the method onActivityResult. The developer must specify the MIME type of the files he expects to receive so that the filter displays only matching documents. For example, to work with images, the type is specified image/*.

Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
intent.addCategory(Intent.CATEGORY_OPENABLE);
intent.setType("application/pdf");
startActivityForResult(intent, READ_REQUEST_CODE);

After the user selects a file, the system will return the URI as a string. This URI must be saved if the application needs to access the file in the future. It is important to use the method takePersistableUriPermissionso that the resolution is maintained even after rebooting the device or closing the application.

Action Intent	Description	Result
ACTION_OPEN_DOCUMENT	Selecting an existing file	URI for reading/writing
ACTION_CREATE_DOCUMENT	Creating a new file	URI for writing
ACTION_OPEN_DOCUMENT_TREE	Selecting a directory	URI for accessing a folder

Working with data streams via ContentResolver. After receiving the URI, the developer opens the InputStream or OutputStream to read or write bytes. Direct work with file system paths in this case is impossible and not required.

Features of working with Android 11+

In versions of Android 11 and higher, access to the root directory of the SD card via ACTION_OPEN_DOCUMENT_TREE was limited. Now applications cannot request access to the entire storage without a compelling reason approved by Google.

Comparison of SAF and direct file paths

The transition to Storage Access Framework is driven by the need to improve security. The traditional method of working with direct paths (File API) assumed that the application had full access to the memory section if the user gave the appropriate permission. This created risks when malware could scan and copy any personal data.

SAF implements the principle of least privilege. The application gains access only to those objects that the user has explicitly selected. This isolates applications from each other and prevents unauthorized collection of information. In addition, SAF allows you to work with cloud storage as easily as with local memory.

However, the new approach also has its limitations that must be taken into account. Working through a URI can be a little slower when copying files in bulk compared to directly accessing bytes on disk. The app logic also becomes more complicated, since it is necessary to handle cases when access has been revoked by the user.

⚠️ Attention: SAF interfaces and capabilities may change with the release of new versions of Android. Always check the official developer documentation for the latest requirements before implementing features.

For tasks that require high performance when working with large volumes of data, direct access may still be preferable, but only within the permitted system directories. In other cases, SAF is the only standard for modern development under Android.

Common errors and ways to solve them

When implementing Storage Access Framework developers often face a number of typical problems. One of the most common mistakes is trying to save a direct path to a file instead of a URI. After rebooting the device, such an application will lose access to data because the physical path may have changed or become inaccessible.

Another problem is related to permission management. If the application does not call a method to save permanent rights (takePersistableUriPermission), access will only be valid for the current session. The user will have to re-select the file each time, which negatively affects the user experience.

It is also worth mentioning the problem with encoding and file types. An incorrectly specified MIME type may result in the desired file simply not appearing in the selection list. It is recommended to use wide type masks if the application supports different formats, or dynamically change the filter depending on the context.

• ❌ Error: Saving string path /storage/emulated/0/... to the database.
• ✅ Solution: Saving the string representation of the URI content://com.android.externalstorage.documents/....
• ❌ Error: Ignoring exception SecurityException when trying to access.
• ✅ Solution: Handling the exception and requesting re-access from the user through the SAF interface.

To debug access problems, it is useful to use system logging tools. They allow you to see which document provider was involved and at what stage the authorization failed. This saves time when searching for reasons for application instability.

The future of file management in Android

Evolution Storage Access Framework continues with each update of the operating system. Google has consistently limited the ability to directly access the file system, making SAF the only reliable way to work with data in the long term. This direction of development is aimed at creating a “sandbox” for each application.

Even deeper integration of cloud services is expected in future versions. Users will be able to select files from various online drives without having to download them to the device first. This will save memory space and speed up work with documents stored in the cloud.

Developers should adapt their products to these changes in advance. Ignoring security trends may result in the application being removed from the store Google Play or becoming inoperable on new smartphones. Investment in the correct implementation of SAF will pay off in the stability of the app.

Is it possible to access the entire SD card through SAF?

Starting with Android 11, access to the entire root directory of external memory through tree selection (ACTION_OPEN_DOCUMENT_TREE) is limited for most applications. This is done to protect user data. Exceptions include file managers and backup applications that have undergone special testing.

What is a URI in the context of the Storage Access Framework?

URI (Uniform Resource Identifier) ​​in SAF is a unique reference identifier that the system issues when you select a file. It does not indicate the physical location of the file on disk, but serves as an access key to the document through the system ContentResolver.

Is it mandatory to use SAF for all applications?

You can use the MediaStore API to access shared media files (photos, video, audio). However, to work with arbitrary files, documents and folders, the use of the Storage Access Framework is a mandatory requirement for modern versions of Android.

How to revoke access granted through SAF?

The user can revoke access in the smartphone settings in the "Applications" -> "Permissions" -> "Files and Media" section. The developer can programmatically call releasePersistableUriPermission to clear stored tokens.