Previous

Next

Integrate GitHub with single sign-on (SSO)

Completed

GitHub provides multiple ways to authenticate and authorize access to its resources.

• Username and password (in combination with another authentication factor): the traditional interactive method where users provide their GitHub username and password to authenticate. GitHub requires all users who contribute code to have one or more forms of two-factor authentication (2FA) enabled.
• SSH keys: keys generated by users and stored in their GitHub accounts, allowing secure access to repositories via the SSH protocol. They accommodate scenarios in which Git operations need to be performed as part of automated scripts or processes (such as continuous integration workflows) without requiring manual input of credentials.
• Personal Access Tokens (PATs): tokens generated in GitHub that act as alternative passwords, allowing access to the GitHub resource that individual users designate. They're commonly used for web-based applications, automation, and accessing the GitHub API. They also provide an alternative to SSH keys in scenarios where firewall restrictions block SSH connectivity.
• OAuth apps: custom-developed and third-party apps that authorize access to GitHub resources without an explicit use of users credentials. They facilitate integration of third-party applications with GitHub.
• GitHub Apps: custom-developed and third-party apps similar to OAuth apps but with additional capabilities, including support for more granular permissions. They constitute the recommended approach to providing programmatic access to GitHub API. GitHub Apps provide a way to integrate third party applications with GitHub repositories and organizations. The facilitated workflow automation, policy enforcement, and the use of custom tools within the GitHub ecosystem.
• GITHUB_TOKEN: a built-in authentication token provided by GitHub Actions and automatically available during workflow execution. It provides scoped access to the repository and is commonly used for automating workflows within GitHub Actions.

Implementing username and password (including two-factor) authentication

You're automatically prompted to create a password when you create a GitHub account. After entering your username and password, you'll be asked to provide a verification code sent to you via email. If you enable 2FA, after you successfully enter your username and password, you'll also be prompted to provide a code that's generated by a time-based one time password (TOTP) application on your mobile device or sent as a text message (SMS).

GitHub also supports SAML (Security Assertion Markup Language)-based single sign-on for organization and enterprise account. In such cases, when you attempt to access the account's resources, GitHub will redirect you to the organization's SAML identity provider (IdP) to authenticate. After you successfully authenticate with your IdP credentials, you'll be automatically redirected back to GitHub account's hosted resources.

Implementing SSH keys authentication

To start, if you don't already have an SSH key pair, generate one using the ssh-keygen utility. This generates a new SSH key pair (public and private keys) and prompts you to choose a location to save the keys. Then copy the contents of the public key (typically id_rsa.pub or id_rsa.pub in the .ssh directory) to your clipboard, use a web browser to open your GitHub account settings page, navigate to the SSH and GPG keys section, select the New SSH key button, and use the content of the clipboard to assign the value to the key, along with assigning to it a descriptive name. Subsequently, you'll be able to use SSH from any computer where the private key is stored to access the target GitHub account.

Alternatively, if you first authenticate by using GitHub CLI, the CLI finds SSH public keys on your machine and will prompt you to select one for upload. In addition, if GitHub CLI doesn't find an SSH public key for upload, it can generate a new SSH public/private keypair and upload the public key to your GitHub account.

Implementing Personal Access Token (PAT) authentication

To start, use a web browser to open your GitHub account settings page and navigate to the Developer settings section. Select Personal access tokens and then select the Generate new token button. Specify the desired scopes, duration, and a descriptive name, and generate it.

Subsequently, you can use the personal access token in workflows, scripts, or applications to authenticate with GitHub APIs. Personal access tokens can be used as an alternative to GITHUB_TOKEN in GitHub Actions workflows. However, you should avoid hardcoding personal access tokens in public repositories or exposing them in unsecured environments.

Implementing GitHub Apps authentication

To start, you need to create a GitHub app. Use a web browser to open your GitHub account settings page and navigate to the Developer settings section. Select GitHub Apps and then select the New GitHub App button. Provide the required details such as the app name, description, permissions, and webhook configuration. Generate and securely store the private key associated with the GitHub App. After creating the GitHub App, install it on the repositories or organizations where you want to use it. During installation, you're prompted to grant the necessary permissions to the GitHub App.

GitHub Apps use access tokens to authenticate API requests. These tokens are generated dynamically and have limited scopes based on the permissions granted to the GitHub App. The GitHub App's access token can be used in workflows, scripts, or applications to interact with GitHub's APIs.

GitHub Apps offer fine-grained permissions control. You can manage the permissions granted to the GitHub App from the GitHub App settings page.

Implementing GITHUB_TOKEN authentication

GITHUB_TOKEN is generated automatically by GitHub Actions for each workflow run. The token is automatically added as a secret to the repository's environment, making it accessible within workflows.

The GITHUB_TOKEN has read and write access to the repository where the workflow runs. It can be used to perform various actions such as cloning the repository, creating issues, and triggering other workflows.

To Access the GITHUB_TOKEN within workflows, use the secrets context. The following example illustrates how to leverage GITHUB_TOKEN to automatically generate a comment on an issue when a pull request is opened:

name: Comment on Issue

on:
  pull_request:
    types: [opened]

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - name: Comment on Issue
        uses: actions/github-script@v4
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const issueNumber = context.payload.pull_request.issue_url.split('/').pop();
            await github.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: issueNumber,
              body: 'We appreciate opening this pull request. We will review it shortly.'
            });

Continue