Configuring OpenID (SSO) based authentication

How to set up OpenID based authentication to protect your 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.

When using OIDC, you’ll need an Authorization Server. In this guide, we will use Keycloak as our Authorization Server as it’s fairly easy to run and setup. It will contain the realm, client ID, user, group, and anything else we will need for logging into the Anka Build Cloud Controller.

This guide will be running the Anka Build Cloud and Keycloak on the same machine. It is meant to give you an idea of how to configure and is not recommended for production.

We will then log into the Anka Build Cloud Controller UI and use the /admin/ui#/controllerGroups page to create limited permissions for your groups.

Setup Keycloak in Docker

Run the docker container

docker run --rm -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:latest

Configure your Keycloak

  1. Follow the instructions in https://www.keycloak.org/getting-started/getting-started-docker to set up your Keycloak:
  • I used myrealm as the Realm name.
  • I created user nathan with the password of nathan (turn off Temporary). I filled in my full name too.
  • When creating the Client, I set anka as the Client ID, clicked Save, then entered https://anka.controller (this is the URL for the controller I run) for the Valid Redirect URIs. I also set Access Type to confidential and enabled Implicit Flow.
  1. Next, create a Client Scope named groups. Once created, under Clients > anka > Client Scopes, add the groups Client Scope (select it and then click Add Selected). Then, back under the groups Client Scope, Mappers, click Add Builtin, and choose groups, then Add Selected.

  2. Under Roles add anka-build-cloud-access.

    The role is what matches with the group name in the Controller UI’s Admin panel where you set specific access permissions for certain groups/users.

  3. You can now create a group called anka-build-cloud-access and under Role Mappings, add the role: anka-build-cloud-access. Then, join it to the user you created.

At this point, you’ll have Keycloak ready to use with your Anka Build Cloud Controller. Though, we need first to enable it.

Enable OpenID in your Controller configuration

In order to enable OpenID, you’ll need to modify your docker-compose.yml (if you’re using our docker package) or the /usr/local/bin/anka-controllerd (if you’re using the native Mac package).

You can find a list of configuration options in the Configuration Reference by searching for ANKA_OIDC

Here is what your docker-compose.yml should look like for use with Keycloak:

  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: "Keycloak"
      ANKA_OIDC_PROVIDER_URL: "http://host.docker.internal:8080/auth/realms/myrealm"
      ANKA_OIDC_CLIENT_ID: "anka"

  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 Keycloak and Login with superuser

OpenID Login Buttons

We first want to log in with superuser (the ANKA_ROOT_TOKEN defined above in the config).

Once logged in, you will see Admin on the left navigation

Admin Navigation

Under the Admin page, we want to add a New Group. The Group Name will be the name of the group you created within Keycloak.

Not using Keycloak? No problem! For example in CyberArk’s Idaptive, you need to create an OpenID Connect Web App, assign your user under Permissions, and then setClaim('groups', 'sso-user-group'); under Tokens > Custom Logic. Once set up, you configure the controller to use ANKA_OIDC_PROVIDER_URL="{OpenID Connect Issuer URL}" and export ANKA_OIDC_CLIENT_ID="{OpenID Connect Client ID}". At this point, you’d add sso-user-group under the Controller’s /admin/ui permissions management panel (using the root token/user) and assign the proper permissions users of the web app can use. We recommend contacting your local IT team to help determining exactly what you’ll need to configure this with your company’s preferred tools.

Managing User/Group Permissions (Authorization)

Once user, group, and roles are created and assigned to each other, you can then add the exact role name from your keycloak (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:

  • get_groups
  • get_registry_disk_info
  • list_images
  • list_nodes
  • list_vms
  • save_image
  • start_vm
  • terminate_vm
  • update_vm
  • view_logs

Controller Permissions

PermissionDescription
Instances
list_vmsgives the user permission to list vms
start_vmgives the user permission to start vm
terminate_vmgives the user permission to terminate vm
Registry
get_registry_filesgives the user permission to get registry files (logs)
view_logsgives the user permission to view log files in dashboard
get_registry_disk_infogives the user permission to get registry disk info
registry_listgives the user permission to list vms on registry
registry_deletegives the user permission to registry delete
Nodes
list_nodesgives the user permission to list nodes
delete_nodegives the user permission to delete node
change_node_configgives the user permission to change node configuration
Node Groups
create_groupgives the user permission to create node groups
get_groupsgives the user permission to view node groups
delete_groupgives the user permission to delete node groups
update_groupgives the user permission to update node groups
add_node_to_groupgives the user permission to add a node to a node group
remove_group_from_nodegives the user permission to remove a node from node group
Distribute VMs
registry_distributegives the user permission to distribute vms from registry
registry_distribute_statusgives the user permission to view distribution statuses
Config
change_configgives the user permission to change global configuration
get_configgives the user permission to view global configuration
Permissions and groups
view_permissionsgives the user permission to view the list of available permissions
view_prmission_groupsgives the user permission to view permission groups
update_permission_groupsgives the user permission to update permission groups
delete_permission_groupsgives the user permission to delete permission groups

Registry Permissions

PermissionDescription
Information about Registry
indexgives the user permission to view the registry index (welcome html file)
get_disk_infogives the user permission to get disk info
List VMs
list_vmsgives the user permission to list vms
Push VMs
head_push_vmgives the user permission to “negotiate” a push (understand which files exists on the server and which files need to be sent)
push_vmgives the user permission to push vm and create new vms or tags
Pull VMs
pull_vmgives the user permission to get a pull vm request (list of files needed for download and their paths)
download_vmgives the user permission to download vm files (as given by pull_vm)
Delete VMs
delete_vmgives the user permission to delete a vm
revertgives the user permission to revert vm versions
File Server
upload_filegives the user permission to upload a file
download_filegives the user permission to download a file
Log Server
get_streamergives the user permission to get an html streamer page (for logs)
stream_loggives the user permission to stream a log file (as given by get_streamer)
get_log_archivegives the user permission to download a log archive (tar.gz)
send_log_eventgives the user permission to send log events (only applies specifically to eventLog)
send_loggives the user permission to send a log file row
Permissions and groups
view_permissionsgives the user permission to view the list of available permissions
view_prmission_groupsgives the user permission to view permission groups
update_permission_groupsgives the user permission to update permission groups
delete_permission_groupsgives 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 Keycloak, which will redirect you to your Keycloak to have you log in with the user you created earlier in this guide. You will then be taken to the Controller UI and be logged in as that user.