API¶

The following documentation describes the classes and functions available for use. The documentation is divided into three groups: 1. The OAuth class which is the public API 2. The client management API 3. The server API

1. OAuth¶

The OAuth class is the primary user interface for the oauth_client package.

The OAuth Class

class oauth_client.OAuth(db_name: str, db_host: str, db_table_name: str, db_create_table: bool = False, resource_owner_username: str = '', jwt_issuer: str = '', jwt_subject: str = '', jwt_audience: str = '')¶

OAuth_Client is a tool to help share data between two machines using the OAuth2.0 client credentials process.

The OAuth Class serves as the primary entrypoint and allows users to:

Create and manage clients through a PostgreSQL backend.
Generate Resource Owner Signatures
Handle the authorization flow
Create web tokens for access
Serve requests for protected resources

In general, there should be good separation of these resources as follows:

The PostgreSQL server (established with 2 users: an admin and a viewer)
The Authorization server (with stored signature, access to the PostgreSQL server)
The Resource server (with access to the public key of the stored signature)

Attributes¶

db_namestr: The name of the database in PostgreSQL. We suggest “clientdb” but can be any valid string.
db_hoststr: The host IP address of the PostgreSQL server. For testing, this can be localhost. For production, the server should exist on a dedicated VM likely with a reverse proxy.
db_table_namestr: The name of the table to store the client credentials. We suggest “stored_tokens”.
db_create_tablebool: Create the table to store the client credentials in the PostgreSQL database. Usually this will be False as the table only needs to be generated once and can be generated using the psql cli directly instead of the Python method.
resource_owner_usernamestr: The username for the resource owner that will be signing the token.
jwt_issuerstr: The issuer of the jwt token. Likely the same as the resource owner.
jwt_subjectstr: The user who requested the token (i.e. the authorized client).
jwt_audiencestr: The recipient for which the token is intended i.e. the resource server.

Methods¶

add_client(): Adds a new client to the PostgreSQL database.
remove_client(): Removes an existing client from the PostgreSQL database.
update_client(): Update a client’s grant type, resource, or generate a new client secret.
create_signature(): Create the resource owner signature for jwt token generation.
server_create_token(): Create a new token for the Authorization server to send to the authorized client.
auth_server(): Run the authorization server.
resource_server(): Run the resource server

There are also two client facing functions that allow the client to request a token and with that token to request a protected resource.

Request a Token

oauth_client.client_request_token(grant_type: str, client_id: str, client_secret: str, resource: str, token_request_url: str) → str¶

A function that allows a client to request the access token.

Parameters¶

grant_typestr: The type of grant that has been given to a client.
client_idstr: The client id issued to a client.
client_secretstr: The client secret issued to a client.
resourcestr: The resource a client is authorized to access.
token_request_urlstr: The URL of the authorization server that issues the token.

Returns¶

string: The token as a jwt string.

Request a Protected Resource

oauth_client.client_request_resource(resource_url: str, token: str) → str¶

A function that allows a client with valid token to access a protected resource.

Parameters¶

resource_urlstr: The fully qualified URL including http/https and api_route for the resource. Example http://127.0.0.1/api_v0.0.1
tokenstr: The access token.

Returns¶

string: The json string of the protected resource.

2. Client management¶

Client management classes and functions provide lower level funcionality upon which the OAuth class depends. The documentation that follows allows developers and users more control over the public API.

The Client Management Module

class oauth_client.client_management.Client(name: str = '', grant_type: str = 'client_credentials', resource: str = '', _date: str = '23052025_12:14:33', _client: dict = <factory>)¶

A class to handle creation and maintenance of authorized clients.

…

Attributes¶

namestr: The name of the authorized user.
grant_typestr: The type of grant to allow. Default client_credentials
resourcestr: The resource on the server that the client is allowed to access.

Methods¶

generate(): Creates a new client with client id and client secret.
store(db, host, table_name): Stores the client id, grant type, resource, and a salted and hashed client secret. In addition, this function deletes the stored client information from the class.
verify(client_id: str, client_secret: str, grant_type: str, resource: str, db, host, table_name, pgpass=False): Compares the stored credentials against the user provided credentials and returns True if all parameters match

generate()¶

Create a new client consisting of a grant_type, client_id client_secret, and resource.

Returns¶

dict: a client dictionary.

store(db: str, host: str, table_name: str)¶

Store the client information in the PostgreSQL database and delete any references from memory.

Parameters¶

dbstr: The name of the database.
hoststr: The host IP address of the PostgreSQL server.
table_namestr: The name of the table in the database.

verify(client_id: str, client_secret: str, grant_type: str, resource: str, db: str, host: str, table_name: str, pgpass=False) → bool¶

Verify that the provided client id, client secret, grant type and resource exactly match the database.

Parameters¶

client_idstr

The client id to verify.

grant_typestr

The type of grant provided to the user.

resourcestr

The resource on the server that the client is allowed to access.

dbstr

The name of the database.

hoststr

The host IP address of the PostgreSQL server.

table_namestr

The name of the table in the database.

pgpassbool

When set to True, the program will search for a .pgpass file (linux) in the /home/username directory. The file should contain a string in the format:

host:port:db_name:username:password

By default, this parameter is set to False which forces the user to authenitcate via the command line.

Returns¶

literal[True] | None: True if all provided parameters match the database and False if any one does not exactly match.

class oauth_client.client_management.GenerateKeyPairs(username: str)¶

A class to create the jwt signature for use by the resource owner to sign tokens.

…

Attributes¶

kid: The randomly generated key id.
key: The randomly generated key using the jwcrypto package.
private_key: The private key.
public_key: The public key.
username: The username of the resource owner.

Methods¶

store_keys(): Stores the kid, public key, and private key in a keyring and deletes the binding and variables from memory.

store_keys()¶: A method to store the signature in a keyring.

class oauth_client.client_management.PostgreSqlHelper(database_name: str = 'clientdb', host: str = '127.0.0.1', pgpass: bool = False)¶

A class to handle interactions with the PostgreSQL backend.

…

Attributes¶

database_namestr

The name of the PostgreSQL database.

hoststr

The database host address.

pgpassbool

When set to True, the program will search for a .pgpass file (linux) in the /home/username directory. The file should contain a string in the format:

host:port:db_name:username:password

By default, this parameter is set to False which forces the user to authenitcate via the command line.

client_keyslist

A list of the default columns to include in the table that stores client id and client secret.

Methods¶

connect(): Establishes a connection to the db and returns a Connection tuple with con connection and cur cursor classes
close(con,cur): Closes the db connection
create(cur, con, table_name, column, data = None): Creates a table in the db
add(cur, con, table_name, data): Adds to a table in the db
query(self, cur, query): Query the connected db

add(cur: cursor, con: connection, table_name: str, data)¶

Adds data to a table.

Parameters¶

curcursor: The cursor class
conconnection: The connection class
table_namestr: The name of the table to create in the PostgreSQL database.
datalist: A list of values to store in the table. The list represents a row of data where each value is a column.

close(con: connection, cur: cursor) → bool | None¶

Closes the PostgreSQL database connection.

Parameters¶

conconnection: The connection class.
curcursor: The cursor class.

Returns¶

literal[True] | None: True if closing the connection was successful. Otherwise returns None.

connect() → Connection¶

Establishes a connection with the PostgreSQL server and returns a Connection class tuple.

Returns¶

tuple: A connection tuple with connection (con) and cursor (cur) classes

create(cur: cursor, con: connection, table_name: str, column: list, data: list = None)¶

Creates a new table in the PostgreSQL database.

Parameters¶

curcursor

The cursor class

conconnection

The connection class

table_namestr

The name of the table to create in the PostgreSQL database.

columnlist

A list of columns along with their datatypes.

Example “[‘grant_type varchar’, ‘client_id varchar’, ‘client_secret varchar’, ‘resource varchar’]”

datalist

A list of values to store in the table. The list represents a row of data where each value is a column.

edit(cur: cursor, con: connection, client_id: str, edit_list: list[tuple])¶

Edit a client in the database.

Parameters¶

curcursor: The cursor class
conconnection: The connection class
client_idstr: The client id to remove from the database.
edit_listlist: A list of tuples specifying the column name and value with which to replace the existing values.

query(cur: cursor, query: str) → list¶

Perform a SQL query of the database.

Parameters¶

curcursor: The cursor class
querystr: The SQL query to perform. Note query string must end with a semicolon.

Returns¶

list: a list of all matching values.

remove(cur: cursor, con: connection, table_name: str, client_id: str)¶

Removes a client from the database.

Parameters¶

curcursor: The cursor class
conconnection: The connection class
table_namestr: The name of the table to create in the PostgreSQL database.
client_idstr: The client id to remove from the database.

class oauth_client.client_management.Token(grant_type: str, client_id: str, client_secret: str, resource: str, token_request_url: str)¶

A class to handle token requests to the authorization server.

…

Attributes¶

valuesstr: The stored token.
grant_typestr: The type of grant that has been given to a client.
client_idstr: The client id issued to a client.
client_secretstr: The client secret issued to a client.
resourcestr: The resource a client is authorized to access.

Methods¶

expires_on(): Returns a unix integer time.
expired(): Returns True if expired and False if not expired.
string(): Returns the access token jwt string.
type(): Returns the type of token which is identical to the grant type.
save(): Saves a token.json file at the root of the directory.
json(): Convert the token to a json string.
get_cached_token(): Retrieve the token if it exists as a token.json file. If not, run get_new_token() method.
get_new_token(): A method to get a new token via an HTTP post reqeust.

expired() → bool¶

Check if the token is expired.

Returns¶

bool: Returns True if token is expired, otherwise returns False.

expires_on() → int¶

Returns the integer unix date of expiration of the token.

Returns¶

int: The unix date as an integer.

get_cached_token() → None¶: Retrieve the saved token and if not present, request a new token.

get_new_token() → str¶

Retrieve a new token.

Returns¶

json: A json string representation of the token.

json() → str¶

Get the json string of the token.

Returns¶

string: The json token.

save() → None¶: Save the token as a json file.

string() → str¶

Get the string representation of the token.

Returns¶

string: The token as a jwt string.

type() → str¶

Get the grant type.

Returns¶

string: The grant type as a string.

oauth_client.client_management.create_table(db: str, host: str, table_name: str) → bool | None¶

A function to create a table in a database.

Parameters¶

dbstr: The name of the database.
hoststr: The host IP address of the PostgreSQL server.
table_namestr: The name of the table in the database.

Returns¶

literal[True] | None: True if successful.

oauth_client.client_management.edit_client(db: str, host: str, client_id: str, grant_type: str = None, resource: str = None, new_client_secret: bool = False) → bool¶

A function to edit a client in the database.

Parameters¶

dbstr: The name of the PostgreSQL database.
hoststr: The IP address of the database.
client_idstr: The client id associated with the client that will be edited.
grant_typestr: The type of credential grant.
resourcestr: The name of the protected resource.
new_client_secretbool: If True, this will create a new client secret for the client id.

Returns¶

literal[True] | None: True if successful.

oauth_client.client_management.get_api_content(resource_url: str, token: str)¶

Retrieve the content of the protected resource.

Parameters¶

resource_urlstr: The full url including http/https and /token path to access and request the protected resource.
tokenstr: The jwt token string used to access the api content.

Returns¶

string: The json encoded response.

oauth_client.client_management.remove(db: str, host: str, table_name: str, client_id: str) → bool | None¶

A function to remove a client from the database.

Parameters¶

dbstr: The name of the database.
hoststr: The host IP address of the PostgreSQL server.
table_namestr: The name of the table in the database.
client_idstr: The client to remove from the database.

Returns¶

literal[True] | None: True if successful.

oauth_client.client_management.retrieve_kid(username: str)¶

Retrieve the key id (kid) of the signature from the keyring storage.

Parameters¶

usernamestr: The username of the resource owner that signed the jwt access token.

Returns¶

string: The key id.

oauth_client.client_management.retrieve_private_key(username: str)¶

Retrieve the private key of the signature from the keyring storage.

Parameters¶

usernamestr: The username of the resource owner that signed the jwt access token.

Returns¶

string: The private key.

oauth_client.client_management.retrieve_pub_key(username: str)¶

Retrieve the public key of the signature from the keyring storage.

Parameters¶

usernamestr: The username of the resource owner that signed the jwt access token.

Returns¶

string: The public key.

3. Servers¶

The Server functions allow the OAuth class to create an Authorization server and a Resource Server. These should always live on two distinct machines.

Authorization Server

class oauth_client.servers.auth_server.CreateToken(iss: str, sub: str, aud: str, username: str, resource: str)¶

A class for use by the Authorization server to create a new token for an authorized client.

…

Attributes¶

Methods¶

generate_new_token(): Creates a new signed jwt token.

generate_new_token() → dict¶

Create the new token.

Returns¶

dict: a dictionary with: * token_type: The grant type. * expires_on: The unix timestamp of token expiry. * not_before: The unix timestamp of token expiry. * resource: The authorized resource * access_token: The jwt access token.

oauth_client.servers.auth_server.create_auth_server(db: str, host: str, table_name: str, username: str, issuer: str, subject: str, audience: str) → Flask¶

Create the Flask server to handle token requests.

Parameters¶

dbstr: The name of the PostgreSQL database.
hoststr: The host IP address for the PostgreSQL database.
table_namestr: The name of the table storing the client credentials.
usernamestr: The username of the resource owner that is the signer of the jwt token.
issuerstr: The issuer of the token.
subjectstr: The subject of the token.
audiencestr: The audience of the token.

Returns¶

Flask: A flask server object.

oauth_client.servers.auth_server.decode_token(token: str, public_key: str, aud: str, iss: str) → bool | None¶

A function to decode a jwt token and confirm its validity.

Parameters¶

token: The token string.
public_key: The public key used to sign the token.
audstr: The audience of the token.
issstr: The issuer of the token.

Returns¶

literal[True] | None: True if token is valid otherwise returns None.

Resource Server

oauth_client.servers.resource_server.create_resource_server(username: str, issuer: str, audience: str, api_route: str, resource_path: str) → Flask¶

Create the resource server to handle requests for the protected resource.

Parameters¶

usernamestr: The username of the resource server owner that signed the token.
issuerstr: The issuer of the token.
audience: str: The recipient for which the token is intended i.e. the resource server.
api_routestr: The URL route to host the resource server.
resource_pathstr: The relative path of the json file on the resource server.

Returns¶

Flask: a flask server object.