GitHub

This section shows you how to use GitHub OAuth2 as an authentication backend for Axoflow Console. It is assumed that you already have a GitHub organization. Complete the following steps.

Prerequisites

Register a new OAuth GitHub application for your organization. (For testing, you can create it under your personal account.) Make sure to:

Set the Homepage URL to the URL of your Axoflow Console deployment: https://<your-console-host.your-domain>/callback, for example, https://axoflow-console.example.com.
Set the Authorization callback URL to: https://auth.<your-console-host.your-domain>/callback, for example, https://auth.axoflow-console.example.com/callback.
Save the Client id of the app, you’ll need it to configure Axoflow Console.
Generate a Client secret and save it, you’ll need it to configure Axoflow Console.

Configuration

Configure authentication by editing the spec.dex.config section of the /var/lib/rancher/k3s/server/manifests/axoflow.yaml file.
1. (Optional) If you’ve used our earlier example, delete the spec.dex.config.staticPasswords section.
2. Add the spec.dex.config.connectors section to the file, like this:
```
dex:
  enabled: true
  localIP: $VM_IP_ADDRESS
  config:
    create: true
    connectors:
    - type: github
      # Required field for connector id.
      id: github
      # Required field for connector name.
      name: GitHub
      config:
        # Credentials can be string literals or pulled from the environment.
        clientID: <ID-of-GitHub-application>
        clientSecret: <Secret-of-GitHub-application>
        redirectURI: <idp.your-host.your-domain/callback>
        orgs:
          - name: <your-GitHub-organization>
```
  Note that if you have a valid domain name that points to the VM, you can omit the localIP: $VM_IP_ADDRESS line.
3. Edit the following fields. For details on the configuration parameters, see the Dex GitHub connector documentation.
  - connectors.config.clientID: The ID of the GitHub OAuth application.
  - connectors.config.clientSecret: The client secret of the GitHub OAuth application.
  - connectors.config.redirectURI: The callback URL of the GitHub OAuth application: https://auth.<your-console-host.your-domain>/callback, for example, https://auth.axoflow-console.example.com/callback.
  - connectors.config.orgs: List of the GitHub organizations whose members can access Axoflow Console. Restrict access to your organization.
Configure authorization in the spec.pomerium.policy section of the /var/lib/rancher/k3s/server/manifests/axoflow.yaml file.
- List the primary email addresses of the users who have read and write access to Axoflow Console under the emails section.
- List the primary email addresses of the users who have read-only access to Axoflow Console under the readOnly.emails section.
Note
```
Use the primary GitHub email addresses of your users, otherwise the authorization will fail.
```
```
  policy:
    emails:
      - username@yourdomain.com
    domains: []
    groups: []
    claim/groups: []
    readOnly:
      emails:
        - readonly-username@yourdomain.com
      domains: []
      groups: []
      claim/groups: []
```
For details on authorization settings, see Authorization.
Save the file.

Restart the dex deployment after changing the connector:

kubectl rollout restart deployment/dex -n axoflow

Expected output:

deployment.apps/dex restarted

Open the main page of your Axoflow Console deployment in your browser. You’ll be redirected to the GitHub authentication page.

After completing the GitHub authentication you can access Axoflow Console.

Getting help

You can troubleshoot common errors by running kubectl logs -n axoflow <dex-container-name>

If you run into problems setting up the authentication or authorization, contact us.