On-premise

• 1: Authentication
• 1.1: GitHub
• 1.2: Google
• 1.3: LDAP
• 2: Authorization
• 3: Prepare AxoRouter hosts

1 - Authentication

These sections show you how to configure on-premises and Kubernetes deployments of Axoflow Console to use different authentication backends.

1.1 - 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

1. 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.

2. 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.

3. Save the file.

4. Restart the dex deployment after changing the connector:

   kubectl rollout restart deployment/dex -n axoflow
   

   Expected output:

   deployment.apps/dex restarted
   

5. 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.

1.2 - Google

This section shows you how to use Google OpenID Connect as an authentication backend for Axoflow Console. It is assumed that you already have a Google organization and Google Cloud Console access. Complete the following steps.

Prerequisites

• To use Google authentication, Axoflow Console must be deployed on a publicly accessible domain name (the $BASE_HOSTNAME must end with a valid top-level domain, for example, .com or .io.)

• Configure OpenID Connect and create an OpenID credential for a Web application.

  • Make sure to set the Authorized redirect URIs 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 and the Client secret of the application, you’ll need them to configure Axoflow Console.

  For details on setting up OpenID Connect, see the official documentation.

Configuration

1. 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:

      connectors:
      - type: google
        id: google
        name: Google
        config:
          # Connector config values starting with a "$" will read from the environment.
          clientID: <ID-of-Google-application>
          clientSecret: <Secret-of-GitHub-application>
      
          # Dex's issuer URL + "/callback"
          redirectURI: <idp.your-host.your-domain/callback>
      
          # Set the value of `prompt` query parameter in the authorization request
          # The default value is "consent" when not set.
          promptType: consent
      
          # Google supports whitelisting allowed domains when using G Suite
          # (Google Apps). The following field can be set to a list of domains
          # that can log in:
          #
          hostedDomains:
          - <your-domain>
      

   3. Edit the following fields. For details on the configuration parameters, see the Dex Google connector documentation.

      • connectors.config.clientID: The ID of the Google application.
      • connectors.config.clientSecret: The client secret of the Google application.
      • connectors.config.redirectURI: The callback URL of the Google application: https://auth.<your-console-host.your-domain>/callback, for example, https://auth.axoflow-console.example.com/callback.
      • connectors.config.hostedDomains: The domain where Axoflow Console is deployed, for example, example.com. Your users must have email addresses for this domain at Google.

2. Configure authorization in the spec.pomerium.policy section of the /var/lib/rancher/k3s/server/manifests/axoflow.yaml file.

   • List the email addresses of the users who have read and write access to Axoflow Console under the emails section.
   • List the email addresses of the users who have read-only access to Axoflow Console under the readOnly.emails section.
   Note

   The email addresses of your users must have the same domain as the one set under `connectors.config.hostedDomains`, 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.

3. Save the file.

4. Restart the dex deployment after changing the connector:

   kubectl rollout restart deployment/dex -n axoflow
   

   Expected output:

   deployment.apps/dex restarted
   

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

   After completing the Google 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.

1.3 - LDAP

This section shows you how to use LDAP as an authentication backend for Axoflow Console. In the examples we used the public demo service of FreeIPA as an LDAP server. It is assumed that you already have an LDAP server in place. Complete the following steps.

1. 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:

      CAUTION:

      This example shows a simple configuration suitable for testing. In production environments, make sure to:

          - configure TLS encryption to access your LDAP server
          - retrieve the bind password from a vault or environment variable. Note that if the bind password contains the `$` character, you must set it in an environment variable and pass it like `bindPW: $LDAP_BINDPW`.
      

          dex:
            enabled: true
            localIP: $VM_IP_ADDRESS
            config:
              create: true
              connectors:
              - type: ldap
                name: OpenLDAP
                id: ldap
                config:
                  host: ipa.demo1.freeipa.org
                  insecureNoSSL: true
                  # This would normally be a read-only user.
                  bindDN: uid=admin,cn=users,cn=accounts,dc=demo1,dc=freeipa,dc=org
                  bindPW: Secret123
                  usernamePrompt: Email Address
                  userSearch:
                    baseDN: dc=demo1,dc=freeipa,dc=org
                    filter: "(objectClass=person)"
                    username: mail
                    # "DN" (case sensitive) is a special attribute name. It indicates that
                    # this value should be taken from the entity's DN not an attribute on
                    # the entity.
                    idAttr: uid
                    emailAttr: mail
                    nameAttr: cn
                  groupSearch:
                    baseDN: dc=demo1,dc=freeipa,dc=org
                    filter: "(objectClass=groupOfNames)"
                    userMatchers:
                      # A user is a member of a group when their DN matches
                      # the value of a "member" attribute on the group entity.
                    - userAttr: DN
                      groupAttr: member
                    # The group name should be the "cn" value.
                    nameAttr: cn
      

   3. Edit the following fields. For details on the configuration parameters, see the Dex LDAP connector documentation.

      • connectors.config.host: The hostname and optionally the port of the LDAP server in “host:port” format.
      • connectors.config.bindDN and connectors.config.bindPW: The DN and password for an application service account that the connector uses to search for users and groups.
      • connectors.config.userSearch.bindDN and connectors.config.groupSearch.bindDN: The base DN for the user and group search.

2. Configure authorization in the spec.pomerium.policy section of the /var/lib/rancher/k3s/server/manifests/axoflow.yaml file.

   • List the names of the LDAP groups whose members have read and write access to Axoflow Console under claim/groups. (Group managers in the example.)
   • List the names of the LDAP groups whose members have read-only access to Axoflow Console under readOnly.claim/groups. (Group employee in the example.)

     policy:
       emails: []
       domains: []
       groups: []
       claim/groups:
         - managers
       readOnly:
         emails: []
         domains: []
         groups: []
         claim/groups:
           - employee
   

   For details on authorization settings, see Authorization.

3. Save the file.

4. Restart the dex deployment after changing the connector:

   kubectl rollout restart deployment/dex -n axoflow
   

   Expected output:

   deployment.apps/dex restarted
   

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.

2 - Authorization

These sections show you how to configure the authorization of Axoflow Console with different authentication backends.

You can configure authorization in the spec.pomerium.policy section of the Axoflow Console manifest. In on-premise deployments, the manifest is in the /var/lib/rancher/k3s/server/manifests/axoflow.yaml file.

You can list individual email addresses and user groups to have read and write (using the keys under spec.pomerium.policy) and read-only (using the keys under spec.pomerium.policy.readOnly) access to Axoflow Console. Which key to use depends on the authentication backend configured for Axoflow Console:

• emails: Email addresses used with static passwords and GitHub authentication.

  With GitHub authentication, use the primary GitHub email addresses of your users, otherwise the authorization will fail.

• claim/groups: LDAP groups used with LDAP authentication. For example:

    policy:
      emails: []
      domains: []
      groups: []
      claim/groups:
        - managers
      readOnly:
        emails: []
        domains: []
        groups: []
        claim/groups:
          - employee
  

3 - Prepare AxoRouter hosts

When using AxoRouter with an on-premises Axoflow Console deployment, you have to complete the following steps on the hosts you want to deploy AxoRouter on. These steps are specific to on-premises Axoflow Console deployments, and are not needed when using the SaaS Axoflow Console.

1. If the domain name of Axoflow Console cannot be resolved from the AxoRouter host, add it to the /etc/hosts file of the AxoRouter host in the following format. Use and IP address of Axoflow Console that can be accessed from the AxoRouter host.

   <AXOFLOW-CONSOLE-IP-ADDRESS> <AXOFLOW-CONSOLE-BASE-URL> kcp.<AXOFLOW-CONSOLE-BASE-URL> telemetry.<AXOFLOW-CONSOLE-BASE-URL> idp.<AXOFLOW-CONSOLE-BASE-URL> authenticate.<AXOFLOW-CONSOLE-BASE-URL>
   

2. Import Axoflow Console certificates to AxoRouter hosts.

   1. On the Axoflow Console host: Run the following command to extract certificates. The AxoRouter host will need these certificates to download the installation binaries and access management traffic.

      k3s kubectl get secret -n axoflow kcp-ca -o=jsonpath='{.data.ca\.crt}'|base64 -d > $BASE_HOSTNAME-kcp-ca.crt
      

      k3s kubectl get secret -n axoflow pomerium-certificates -o=jsonpath='{.data.ca\.crt}'|base64 -d > $BASE_HOSTNAME-pomerium-ca.crt
      

      This will create two files in the local folder. Copy them to the AxoRouter hosts.

   2. On the AxoRouter hosts: Copy the certificate files extracted from the Axoflow Console host.

      • On Red Hat: Copy the files into the /etc/pki/ca-trust/source/anchors/ folder, then run sudo update-ca-trust extract. (If needed, install the ca-certificates package.)
      • On Ubuntu: Copy the files into the /usr/local/share/ca-certificates/ folder, then run sudo update-ca-certificates

1. curl https://kcp.<your-host.your-domain>

1. Now you can deploy AxoRouter on the host.