indieauth-helpers 1.0.1

IndieAuth authorization and callback helpers.

Python IndieAuth Helpers

This package contains helper scripts for implementing an IndieAuth-compliant authentication flow.

Installation

To install this package, run the following command:

pip install indieauth_helpers

You can import the package using the following line of code:

import indieauth_helpers

Usage

This project creates two handler functions that you can use in your programs:

• A discover_endpoints function to find specified IndieWeb endpoints (i.e. authorization_server)
• A indieauth_callback_handler function to handle a response from an IndieAuth server after a visitor has authorized access to an account.

discover_endpoints

discover_endpoints(domain, headers_to_find)

To use this function, specify:

• The domain on which endpoint discovery should take place.
• A list of headers that should be returned by the server.

You can use this script to find any header in a HTTP Header tag or a HTML tag.

The values that you are most likely going to use this function for are:

• authorization_endpoint
• token_endpoint
• micropub
• microsub

The function returns a dictionary of values depending on what endpoints you want to find

Here is an example of the discover_endpoints function in use:

import indieauth_helpers

domain = "https://jamesg.blog"

headers_to_find = ["authorization_endpoint", "token_endpoint"]

endpoints = indieauth_helpers.discover_endpoint(domain, headers_to_find)

print(endpoints)

This code returns the following:

{
    'authorization_endpoint': 'https://auth.jamesg.blog/auth',
    'token_endpoint': 'https://auth.jamesg.blog/token'
}

indieauth_callback_handler

message, response = indieauth_callback_handler(
    code, # The code that was returned by the IndieAuth server
    state, # The state that was returned by the IndieAuth server
    token_endpoint, # The token endpoint to which the callback POST request should be sent
    code_verifier, # The code verifier that was used to generate the code
    session_state, # The session state that was generated by the client
    me, # The URL of the user's profile
    callback_url, # The URL to which the user should be redirected if authentication is successful
    client_id, # The URL of the page that identifies the client
    required_scopes # The scopes that the client needs
)

This function verifies that an authorization server has returned a valid response and redeems a token.

This function will return a message and a None value for response if there was an error. The message value tells you what went wrong during the token verification process.

You can leave the "me" value equal to None if any URL should be able to access your service. Otherwise, set "me" to the URL of the profile that should be able to access your service. Setting a me value other than None may be useful if you are building personal services that nobody else should be able to access.

If successful, this function will return the JSON object returned by an IndieAuth authorization server.

Here is an example of the function in action:

import indieauth_helpers

message, response = indieauth_callback_handler(
    "CODE_FROM_AUTHORIZATION_SERVER",
    "STATE_FROM_AUTHORIZATION_SERVER",
    "https://auth.jamesg.blog/token",
    "CODE_VERIFIER_FROM_CLIENT",
    "STATE_IN_SESSION",
    "jamesg.blog",
    "https://app.jamesg.blog/callback",
    "https://jamesg.blog/callback",
    ["read", "write]
)

print(response)

When successful, this code returns the following:

{
    "me": "https://jamesg.blog/",
    "access_token": "ACCESS_TOKEN",
    "scope": "SCOPE_LIST"
}

License

This project is licensed under the MIT license.

Contributors

• capjamesg