Skip to content

Auth

The auth module provides functions for handling authentication to the GitHub API when making requests. Currently, this module only supports authentication as an installation via GitHub Apps, exchanging a GitHub App's private key for an installation access token that can be used to authenticate requests to the GitHub API.

GitHub provide documentation on this process here: Authenticating with GitHub Apps.

Usage

Within the Policy Methods Library, the authentication methods defined in this module are used by the Clients module. These methods often appear when initialising clients that require authentication, such as the REST API client. GitHub App credentials can be passed to these clients, which will then use the methods defined in this module to authenticate requests to the GitHub API.

In addition to this, the methods defined in this module can also be used directly should you with to get an installation access token for a GitHub App installation and use it yourself. You can import the methods defined in this module for isolated use as follows:

from policy_methods_library.github.auth import get_access_token

# Example usage of the get_access_token method

## Get Variables from Environment (In practice, these would likely be stored in a secrets manager and accessed directly from there).

app_id = os.getenv("GITHUB_APP_ID")
private_key = os.getenv("GITHUB_APP_PRIVATE_KEY")
github_organisation = "your_github_organisation"

## Exchange GitHub App credentials for an installation access token.

access_token = get_access_token(app_id, private_key, github_organisation)

print(access_token)  # This is the token you can use to authenticate requests to the GitHub API.

GitHub App Setup

To use the authentication methods defined in this module, you will need to set up a GitHub App and install it on the relevant repositories or organisations that you want to interact with via the GitHub API.

With this GitHub App created and installed, you will need to make note of the following details, which will be required to authenticate via the methods defined in this module:

  • APP_ID: The ID of your GitHub App.
  • PRIVATE_KEY: The private key of your GitHub App, which can be generated in the GitHub App settings. This should be stored securely, such as in a secrets manager or environment variable (This will be a .pem file).

Auth Module Contents

get_access_token()

Generates an access token for the GitHub App to authenticate with the GitHub API.

Parameters:

Name Type Description Default
app_id str

The GitHub App's identifier.

 required
private_key str

The GitHub App's private key in PEM format.

 required
organisation str

The name of the GitHub organisation.

 required

Returns:

Name Type Description
str str

An access token that can be used to authenticate API requests.

Raises:

Type Description
ValueError

If any of the required parameters are missing or if there are issues with generating the JWT or retrieving the installation ID.
Source code in src/policy_methods_library/github/auth.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def get_access_token(app_id: str, private_key: str, organisation: str) -> str:
    """Generates an access token for the GitHub App to authenticate with the GitHub API.

    Args:
        app_id (str): The GitHub App's identifier.
        private_key (str): The GitHub App's private key in PEM format.
        organisation (str): The name of the GitHub organisation.

    Returns:
        str: An access token that can be used to authenticate API requests.

    Raises:
        ValueError: If any of the required parameters are missing or if there are issues with generating the JWT or retrieving the installation ID.
    """

    # Validate params
    if not app_id:
        raise ValueError("GitHub App ID is required.")
    if not private_key:
        raise ValueError("GitHub App private key is required.")
    if not organisation:
        raise ValueError("GitHub organisation name is required.")

    # Generate a JWT and retrieve the installation ID for the organisation
    jwt = _generate_jwt(app_id, private_key)
    installation_id = _get_installation_id(organisation, jwt)

    # Prepare headers for the API request to generate an access token
    headers = {
        "Authorization": f"Bearer {jwt}",
        "Accept": "application/vnd.github.v3+json",
    }

    # Make API request to generate an access token for the installation and return the token
    response = requests.post(
        f"https://api.github.com/app/installations/{installation_id}/access_tokens",
        headers=headers,
        timeout=10,
    )
    response.raise_for_status()
    return response.json().get("token")