Utilizing HTTP Authorization Request Header in Empress for User Authentication and Secure Request Handling

Developers
1

Introduction

This guide will provide a comprehensive overview of the HTTP Authorization request header in Empress, a feature introduced in the v11.0.3 release. As a developer, understanding and leveraging this feature is crucial for user authentication and request handling.

Overview

The HTTP Authorization request header is a component in the HTTP protocol that contains the credentials needed to authenticate a user with a server. The header is structured with the authorization type—token or Basic—and the corresponding token.

Authorization: <type> <token>

The <token> is a combination of api-key and api-secret, separated by a colon.

Generating API Key and API Secret

To generate your API Key and API Secret, follow these steps:

  1. Navigate to the User list and select a user.
  2. Access the “Settings” tab (skip this step if tabs are not visible).
  3. Expand the API Access section and select Generate Keys.
  4. A popup will appear with the API Secret. Safely store this value (e.g., in a Password Manager).
  5. An “API Key” field will also be visible in this section.

With these keys, you can now authenticate your API requests. Note that all requests made with these keys will be logged against the user selected in Step 1. This implies that user roles will be checked against this user. For API calls, you have the option to create a new user.

Token Authentication

To use token-based authentication, set your HTTP header as follows:

Authorization: token <api_key>:<api_secret>

Here’s an example in Python:

import requests

url = "http://frappe.local:8000/api/method/frappe.auth.get_logged_user"
headers = {
    'Authorization': "token <api_key>:<api_secret>"
}
response = requests.request("GET", url, headers=headers)

Basic Authentication

The “Basic” authentication scheme combines the api_key and api_secret with a colon and base64 encodes the resulting string.

Authorization: Basic base64encode("<api_key>:<api_secret>")

Here’s an example in Python:

import requests
import base64

url = "http://frappe.local:8000/api/method/frappe.auth.get_logged_user"
headers = {
    'Authorization': "Basic %s" % base64.b64encode(<api_key>:<api_secret>)
}
response = requests.request("GET", url, headers=headers)

OAuth 2 Access Token Authentication

If you’re using an OAuth 2 Access Token to authenticate requests, the token is an opaque access_token string provided by the Empress Server after setting up OAuth 2 and generating the token.

Authorization: Bearer access_token

Here’s an example in Python:

import requests

url = "http://frappe.local:8000/api/method/frappe.auth.get_logged_user"
headers = {
    "Authorization": "Bearer %s" % access_token
}
response = requests.request("GET", url, headers=headers)

Conclusion

The HTTP Authorization request header is a key feature in Empress that enables user authentication and secure request handling. With the flexibility of token-based, Basic, and OAuth 2 Access Token authentication, developers can effectively manage and secure API calls, providing a robust foundation for business solution development and customization.