GitHub

1. Create A GitHub App

   GitHub Apps allow external services to authenticate users through GitHub's OAuth system. To set up SSO for the platform, create a new OAuth App in GitHub:

   • Navigate to Settings > Developer Settings > OAuth Apps in GitHub.

   • Click on Create a new OAuth App.

   • Configure the OAuth App with the following settings:

     • Application name: Platform Login via GitHub
     • Homepage URL: https://$VCLUSTER_PRO_HOSTNAME
     • Authorization callback URL: https://$VCLUSTER_PRO_HOSTNAME/auth/github/callback

   • After creating the app, note the $GITHUB_CLIENT_ID and $GITHUB_CLIENT_SECRET. These is required in the next step.

   info

   Replace $VCLUSTER_PRO_HOSTNAME with your actual platform hostname.

2. Create platform config for GitHub

   To enable GitHub SSO for the platform, update the configuration:

   • Navigate to Admin > Config in the platform interface.
   • Adjust your configuration as shown below:
   GitHub SSO Configuration

   auth:
     # Tell loft to use github authentication
     github:
       #
       #
       # REQUIRED CONFIGURATION
       #
       #
       # ClientID of the github application. Can be string literal or pulled from the environment.
       clientId: $GITHUB_CLIENT_ID
       # ClientSecret of the github application. Can be string literal or pulled from the environment.
       clientSecret: $GITHUB_CLIENT_SECRET
       # Callback URL in the form of https://your-loft-domain/auth/github/callback
       redirectURI: https://vcluster-platform.my.domain/auth/github/callback
       #
       #
       # OPTIONAL CONFIGURATION
       #
       #
       # (Optional) vCluster Platform queries the following organizations for group information.
   	# Group claims are formatted as "(org):(team)".
   	# For example if a user is part of the "engineering" team of the "coreos"
   	# org, the group claim would include "coreos:engineering".
   	#
   	# If orgs are specified in the config then user MUST be a member of at least one
   	# of the specified orgs to authenticate with loft.
   	orgs:
   	  # Organization name in github (not slug, full name)
   	- name: My Organization
   	  # (Optional) Names of teams in a github organization. A user will be able to
   	  # authenticate if they are members of at least one of these teams.
   	  teams:
   	  - myteam
       # (Optional) Required ONLY for GitHub Enterprise.
       # This is the Hostname of the GitHub Enterprise account listed on the
   	# management console.
       hostName: my-github.org
       # (Optional) Required ONLY for GitHub Enterprise.
       # Used to support self-signed or untrusted CA root certificates.
       rootCA: /certs/github.ca

   Configuration options explained:

   • clientId: The Client ID from the GitHub OAuth App.
   • clientSecret: The Client Secret from the GitHub OAuth App.
   • redirectURI: The Authorization callback URL specified in the GitHub OAuth App.
   • orgs: Specify GitHub organizations and teams allowed to access the platform.
   • hostName: Custom GitHub Enterprise hostname (if applicable).
   • rootCA: Path to a custom root certificate for GitHub Enterprise (if applicable).

3. Authenticate via GitHub

   After saving the new configuration, the platform should restart. Users can now log in via GitHub:

   • Access the platform login page.
   • Click on the "Login with GitHub" option.
   • Authenticate with GitHub credentials.
   • Grant the requested permissions to the GitHub OAuth App.
   warning

   Users must grant access to the organization configured in step 2. Without this access, they are not going to be able to log in.

4. Disable Username + Password Authentication (optional)

   To turn off password-based authentication, navigate to Admin > Config add these two lines to your config:

   Disable password-based authentication

   auth:
     oidc: ...             # This is your SSO configuration (make sure this is working!)
     password:
       disabled: true      # Disable password-based authentication