# GitHub This section shows you how to use GitHub OAuth2 as an authentication backend for AxoConsole. 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 AxoConsole deployment: `https:///callback`, for example, `https://axoflow-console.example.com`. * Set the **Authorization callback URL** to: `https://auth./callback`, for example, `https://auth.axoflow-console.example.com/callback`. ![OAuth GitHub application registrations](/docs/axoflow/deploy/onprem/authentication/github/github-oauth-app.png) * Save the **Client id** of the app, you’ll need it to configure AxoConsole. * Generate a **Client secret** and save it, you’ll need it to configure AxoConsole. ## Configuration 1. Verify that Dex is configured as the OIDC provider in the `/var/lib/rancher/k3s/server/manifests/axoflow.yaml` file: * `chalco.oidc.enabled: true` * `chalco.oidc.provider: "dex"` For example: ``` oidc: enabled: true provider: "dex" ``` 2. 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](../../../../docs/axoflow/deploy/onprem/deployment-guide/index.md), 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: clientSecret: redirectURI: orgs: - name: ``` 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./callback`, for example, `https://auth.axoflow-console.example.com/callback`. * If you want to fetch every GitHub group, replace the entire `orgs` section with the `loadAllGroups: true` * `connectors.config.orgs`: List of the GitHub organizations whose members can access AxoConsole. Restrict access to your organization. 3. Configure authorization in the `kcp.rbac.roles` section of the `/var/lib/rancher/k3s/server/manifests/axoflow.yaml` file. The following roles are available in AxoConsole by default: * `IAMadmin`: Can manage the roles and permissions to access AxoConsole. Only this role can make changes on the **Settings > Roles** page. * `admin`: Has full access to AxoConsole, but has only read access to the **Settings > Roles** page. * `infrastructureManager`: Can manage the infrastructure (without the permissions to view or tap log contents, or to rehydrate data). Has full access to the following pages: **Activity Logs** , **Alerting** , **Routers** , **Sources** , **Flows** , **Provisioning** , **Search Logs**. Can tap into service logs. * `infrastructureViewer`: Similar to **infrastructure-manager** , but can only view the pages. Can tap into service logs. * `contentManager`: Can view log content and manage content related details like flows (without the permissions to manage infrastructure, but including access to view infrastructure details). * Has full access to the **Rehydration** page. * Can view and modify **Flows** , but can’t create or delete them. * Can view **Routers** , **Sources** , **Search Logs** , **Analytics**. * Can tap into logs. * `contentViewer`: Can view content like analytics, log search, log tapping (without the permissions to manage or view infrastructure details). * Can view **Search Logs** , **Analytics**. * Can tap into logs. If you need other roles, [contact the Axoflow support team](). Composing other roles is possible as part of a custom integration. You can use email addresses or GitHub groups to assign your users to AxoConsole user roles. To use the groups fetched from GitHub, prefix the name of the GitHub group with `groups:`, and add them to the related roles under `kcp.rbac.roles..groups`. For example: ``` rbac: createRoles: true createRoleBindings: true roles: IAMadmin: groups: - groups:iamadmin admin: groups: - groups:admins contentViewer: groups: - groups:readonly ``` * A specific email address, for example, `email:username@example.com` Note * The user must be able to authenticate to AxoConsole using this email address, so authentication must be properly set up. * Multiple identity providers may allow authentication with the same email address, possibly with different level of ownership validation. * An entire email domain, for example, `emaildomain:example.com`. Any user who authenticates with an email address belonging to this email domain will have access to the role. * A user group. The format of the group depends on the OID provider. * If you’re using AxoConsole as a SaaS, specify the group in the following format: `cognito:groups:`, for example, `cognito:groups:ExampleGoogleSaml:Operator`. * If you’re using an on-prem AxoConsole deployment, specify the group in the following format: `groups:` for example, `groups:operator`. * A specific session of an authenticated user, in the following format: `user:`, for example: `user:42c4e962-f077-705f-138f-f01ba1220c44`. * Every authenticated user: `axoflow:user` For details on authorization settings, see [Authorization](../../../../docs/axoflow/deploy/onprem/authorization/index.md). 4. Save the file. 5. Restart the dex deployment after changing the connector: ``` kubectl rollout restart deployment/dex -n axoflow ``` Expected output: ``` deployment.apps/dex restarted ``` 6. Open the main page of your AxoConsole deployment in your browser. You’ll be redirected to the GitHub authentication page. After completing the GitHub authentication you can access AxoConsole. ## Getting help You can troubleshoot common errors by running `kubectl logs -n axoflow ` If you run into problems setting up the authentication or authorization, [contact our support team]().