Configuring OpenID Connect (OIDC) / SSO based authentication

How to set up OIDC / SSO for the Anka Build Cloud Controller UI.

This guide and feature require an Anka Enterprise Plus license.

If you’re using root token auth for your Controller UI, without certificate authentication, Nodes will no longer be able to connect to port 80 (or whatever port you’ve set) when running ankacluster join. You’ll need to setup an interface for them to communicate. Or, use a User Access Key.

You must have at least one node with a Enterprise or higher license joined to the Controller for these features to work.

Many organizations and developers are already familiar with OpenID Connect (OIDC). OIDC is a layer that sits on top of OAuth 2.0 and performs the authorization necessary to access protected resources, such as the Anka Build Cloud Controller.

Usage Instructions

When using OIDC, you’ll need an Authorization Provider or Server. Most of our customers use Providers like Okta, Cyberark’s Idaptive, and others. we won’t get into the specifics for these tools as they often differ greatly. However we will go through several general things you need to know, regardless of provider.

We currently only support Implicit flow.
Your provider config must allow a redirect to the Anka Controller URL homepage. The URL doesn’t need to be public, but must match the hostname or IP (and port) you use locally.
The controller/your browser will request certain scopes from the provider. These scopes have claims attached. By default, we look for openid, profile, and groups.
Within the scopes, we look for claims. The following claims are required (by default): name (part of profile) & groups. These are changeable with ANKA_OIDC_GROUPS_CLAIM and ANKA_OIDC_USERNAME_CLAIM in your controller’s config. In version 1.29.0, we will also look for scopes using the values of those ENVs.
Once the scopes are requested successfully, the data returned needs to be in a specific format (id_token & token). We make the request with response_type to ensure this.
The groups claim is expected to be an array of strings, each correlating to a Controller permission group.

Here is an example config showing what it looks like for a user with Okta:

  anka-controller:
    container_name: anka-controller
    build:
       context: .
       dockerfile: anka-controller.docker
    ports:
       - "8090:80"
    volumes:
       - /Users/myUserName:/mnt/cert
    depends_on:
       - etcd
       - anka-registry
    restart: always
    environment:
      ANKA_REGISTRY_ADDR: "https://anka.registry:8089"
      ANKA_USE_HTTPS: "true"
      ANKA_SKIP_TLS_VERIFICATION: "false"
      ANKA_SERVER_CERT: "/mnt/cert/anka-controller-crt.pem"
      ANKA_SERVER_KEY: "/mnt/cert/anka-controller-key.pem"
      ANKA_CA_CERT: "/mnt/cert/anka-ca-crt.pem"
      ANKA_ENABLE_AUTH: "true"
      ANKA_ROOT_TOKEN: "1111111111"
      ANKA_OIDC_DISPLAY_NAME: "Okta SSO"
      ANKA_OIDC_PROVIDER_URL: "https://dev-193371238.okta.com/oauth2/default"
      ANKA_OIDC_CLIENT_ID: "0oa7a07mc0kQxyfrusdd"

  anka-registry:
    container_name: anka-registry
    build:
        context: .
        dockerfile: anka-registry.docker
    ports:
        - "8089:8089"
    restart: always
    volumes:
      - "/Library/Application Support/Veertu/Anka/registry:/mnt/vol"
      - /Users/myUser/:/mnt/cert
    environment:
      ANKA_USE_HTTPS: "true"
      ANKA_SKIP_TLS_VERIFICATION: "false"
      ANKA_SERVER_CERT: "/mnt/cert/anka-controller-crt.pem"
      ANKA_SERVER_KEY: "/mnt/cert/anka-controller-key.pem"
      ANKA_CA_CERT: "/mnt/cert/anka-ca-crt.pem"
      ANKA_ENABLE_AUTH: "true"
      ANKA_OIDC_DISPLAY_NAME: "Keycloak"
      ANKA_OIDC_PROVIDER_URL: "http://host.docker.internal:8080/auth/realms/myrealm"
      ANKA_OIDC_CLIENT_ID: "anka"

The OIDC ENVs must be set for both services.

After that, just docker-compose down -t 50 && docker-compose up -d and try accessing the Controller at its HTTPS URL or IP. If you did everything correctly (you enabled certificate authentication and joined your node right?), you should see a Log In box with two options: Login with Okta SSO and Login with superuser.

OpenID Login Buttons

Managing User/Group Permissions (Authorization)

You can then add the exact groups claim name from your SSO provider (or other authorization server software) to the controller’s permission management panel. This gives any users associated to the group in that cloud permission group the specific permissions to the API and even controller UI.

By default, ANKA_ENABLE_AUTH will not use authorization/permissions and allow any certs or users to connect to all API endpoints and pages in the UI. In order to enable Authorization, you will need to include specific ENVs in your config:

ANKA_ENABLE_CONTROLLER_AUTHORIZATION works for both combined and standalone (docker) packages.
ANKA_ENABLE_REGISTRY_AUTHORIZATION is for the combined (controller + registry in one binary) package only.
ANKA_ENABLE_AUTHORIZATION is only for the standalone registry package.

Permission groups are configurable from your Controller’s https://<controller address>/admin/ui page. You can target and add permissions for either the group name or the username (which is different between the various Advanced Security Features we offer).

This feature requires Enterprise Plus. The regular enterprise license automatically adds all permissions to each certificate or token that is used and gives no control over them.

This also requires that you’ve enabled Root Token Authentication, giving you super user access to the controller UI and permissions.

The permission groups here differ from the groups you assign to nodes within the Controller UI.

The Available Permissions list will display all of the permissions we can assign to the group (see below for the full list). These permissions will allow plugins/users (like Jenkins) to communicate with the Controller & Registry:

Minimum Recommended Permissions

get_groups
get_registry_disk_info
list_images
list_nodes
list_vms
save_image
start_vm
terminate_vm
update_vm
view_logs

Controller Permissions

Permission	Description
Instances
`list_vms`	gives the user permission to list vms
`start_vm`	gives the user permission to start vm
`terminate_vm`	gives the user permission to terminate vm
Registry
`get_registry_files`	gives the user permission to get registry files (logs)
`view_logs`	gives the user permission to view log files in dashboard
`get_registry_disk_info`	gives the user permission to get registry disk info
`registry_list`	gives the user permission to list vms on registry
`registry_delete`	gives the user permission to registry delete
Nodes
`list_nodes`	gives the user permission to list nodes
`delete_node`	gives the user permission to delete node
`change_node_config`	gives the user permission to change node configuration
Node Groups
`create_group`	gives the user permission to create node groups
`get_groups`	gives the user permission to view node groups
`delete_group`	gives the user permission to delete node groups
`update_group`	gives the user permission to update node groups
`add_node_to_group`	gives the user permission to add a node to a node group
`remove_group_from_node`	gives the user permission to remove a node from node group
Distribute VMs
`registry_distribute`	gives the user permission to distribute vms from registry
`registry_distribute_status`	gives the user permission to view distribution statuses
Config
`change_config`	gives the user permission to change global configuration
`get_config`	gives the user permission to view global configuration
Permissions and groups
`view_permissions`	gives the user permission to view the list of available permissions
`view_prmission_groups`	gives the user permission to view permission groups
`update_permission_groups`	gives the user permission to update permission groups
`delete_permission_groups`	gives the user permission to delete permission groups

Registry Permissions

Permission	Description
Information about Registry
`index`	gives the user permission to view the registry index (welcome html file)
`get_disk_info`	gives the user permission to get disk info
List VMs
`list_vms`	gives the user permission to list vms
Push VMs
`head_push_vm`	gives the user permission to “negotiate” a push (understand which files exists on the server and which files need to be sent)
`push_vm`	gives the user permission to push vm and create new vms or tags
Pull VMs
`pull_vm`	gives the user permission to get a pull vm request (list of files needed for download and their paths)
`download_vm`	gives the user permission to download vm files (as given by pull_vm)
Delete VMs
`delete_vm`	gives the user permission to delete a vm
`revert`	gives the user permission to revert vm versions
File Server
`upload_file`	gives the user permission to upload a file
`download_file`	gives the user permission to download a file
Log Server
`get_streamer`	gives the user permission to get an html streamer page (for logs)
`stream_log`	gives the user permission to stream a log file (as given by get_streamer)
`get_log_archive`	gives the user permission to download a log archive (tar.gz)
`send_log_event`	gives the user permission to send log events (only applies specifically to eventLog)
`send_log`	gives the user permission to send a log file row
Permissions and groups
`view_permissions`	gives the user permission to view the list of available permissions
`view_prmission_groups`	gives the user permission to view permission groups
`update_permission_groups`	gives the user permission to update permission groups
`delete_permission_groups`	gives the user permission to delete permission groups

Once you’ve added all of the proper permissions, you can now go back to the main Controller page and log out of the superuser. You can now choose Login with Okta SSO, which will redirect you to your Okta to have you log in with your user. You will then be taken to the Controller UI and be logged in as that user.