OpenID Connect Setup

Overview

Akka supports Single Sign-On (SSO) integrations via OpenID Connect (OIDC) with third party providers such as Auth0, Okta, and others. The Akka CLI supports configuring the desired OpenID Connect integration.

For assistance during the setup, please contact our support team.

Requirements

The Akka CLI
Superuser access for Akka billing organization
Access to OpenID Connect Provider configuration for application registration
Ability to create DNS records for company domain (e.g. “company.com”)

The following steps need to be performed to configure external authentication via OpenID Connect for your Akka organization:

Verify you have the appropriate permission in your Akka organization

Only a superuser can complete the Akka OIDC configuration for your Akka organization. You can check your current roles/permissions within your Akka organization by running the following CLI commands:

akka organizations list

Check the ROLES column in the output of the command for the organization you would like to configure and ensure you see superuser in the list of roles.

Register Akka as a new OpenID Connect client application

The specific instructions on how this is done will depend on which OpenID Connect provider Akka is being integrated with. Typically, this will involve registering a new application with the provider, with that registration requiring information about the new application.

The necessary information for Akka is:

Origin or Application URL: https://console.akka.io
Allowed Callback or Redirect URL: https://console.akka.io/login/callback
Grant Type: Authorization Code Flow

Below are the instructions for configuring a new OpenID Connect application with some common/popular providers:

For the above options, or any other OpenID Connect compliant identity provider, consult your vendor’s documentation for the specific steps to register a new OpenID Connect client application.

Once Akka is registered as a new client application for your OpenID Connect identity provider, note the following information:

client-id: this is generated by your provider
client-secret: unless using the private-key-jwt or none authentication methods, you will need this. It is generated by your provider, keep it confidential
issuer: this the base URL of your OIDC provider, before the .well-known path
auth-method: one of basic, post, jwt, private-key-jwt, or none, see here for more details
groups (optional): which OIDC/OAuth2 claim your provider places group membership into

Configure your Akka organization for OIDC

Once Akka has been registered with your OpenID Connect provider, and the above information has been collected, the specific Akka organization can be configured for external authentication.

Before the Akka organization is configured for external authentication, verify the following information to prevent an invalid or partial Akka registration:

email domain: this is the domain name (only) portion of your company’s fully qualified domain name, and must match the domain name of all of your company’s users email addresses. For example, for an admin user with email address [email protected], this is the company.com portion.
issuer: this the full URL of your OpenID Connect identity provider, up to but not including the OIDC configuration discovery path. The easiest way to ensure this is correct is to start from your OpenID Connect provider’s discovery URL (e.g. https://my-identity-server.company.com/providers/oidc/.well-known/openid-configuration), and simply remove the well-known OIDC discovery path (the .well-known/openid-configuration portion, so e.g. https://my-identity-server.company.com/providers/oidc).
group-claim: this is strictly optional, but if provided, should point to a OpenID Connect user info field that enumerates each user’s group memberships, and will allow for you to control access to Akka via your OpenID Connect identity provider (via user’s group membership).

In case your organization users' emails use multiple domains, this step has to be applied for every domain.

To perform this configuration, the following command needs to be run (note the command line arguments are part of the same command):

akka organizations auth add openid \
    --auth-method {auth-method or basic} \
    --client-id {client-id} \
    --client-secret {client-secret} \
    --email-domain {your company domain name} \
    --issuer {issuer} \
    --organization {your Akka organization’s unique ID}

Additionally, if a groups claim is configured for group membership with your identity provider:

    --groups-claim {groups}

Additional help/notes can be found by using the Akka CLI’s “help” feature, via:

akka organization auth add openid --help

Upon successful execution of the above command, the console output will include the following details:

Organization Auth Domain ID (unique ID)
Akka domain challenge record (fully qualified domain name)
Akka domain challenge TXT record data

Keep the above details as they will be needed in the next step.

Verifying your company’s domain

Each Akka organization wanting to use external OpenID Connect authentication must provide proof that they are the owner of the domain name they are associating with their company and users (via email address). In order to prove that ownership, a TXT domain record must be placed in the root of the owning organization’s DNS records.

The fully qualified domain name of the TXT record that Akka will attempt to validate was provided in the output of the Akka CLI command from the previous step, along with the value that needs to be verified from that record.

For reference, the DNS record prefix will always be: _kalix-domain-challenge, so an example fully-qualified domain name might look like: _kalix-domain-challenge.company.com. The DNS record’s expected value will look like:

> token=44e4d186697e11efa96a639d11421c46eaa72bbadc07ea174fba8e46b126db32,expiry=2025-10-02T18:39:56.348436801Z

For example instructions on how to add a TXT record to your DNS registrar, see here.

Once you have the TXT record registered with your DNS provider, you can view the status of the registration check via:

akka organization auth show {organization auth-domain ID} --organization {organization ID}

Alternatively, use the command:

akka organization auth list --organization {organization ID}

In both cases, checking for the STATUS (or VERIFIED) columns (respectively). The check is performed every 5 minutes, so it can take up to 5 minutes after the DNS TXT record is registered for Akka to verify it.

Note that after verification, you can remove this domain challenge DNS record from your DNS provider (verification is only performed once).

Migrate your user(s) over to external authentication

After Akka has successfully verified the ownership of the DNS domain name associated with your Akka organization, any new users that authenticate to Akka using an email address matching your organization’s email domain name (e.g. [email protected] matches company.com) will automatically be directed to your OpenID Connect identity provider on first (and all subsequent logins). Those users are “tied” to the Akka organization, and linked to the OpenID Connect provider from creation.

For users which already existed in the organization previously, and have a matching email (domain) address associated with their Akka user account, they will begin being prompted to migrate over to using external authentication via the configured OpenID Connect provider on each subsequent login.

Choosing to “migrate your account” will redirect the existing user to the OpenID Connect provider for initial authentication, and if successful, the user will then be tied to the organization and linked to the OpenID Connect provider for authentication.

Creating OIDC groups for Akka access

Akka roles are defined at either the organization or project level. A group can have one or more roles and be applied to an organization and/or projects. It is important to note that only one role can be added to a group at a time via individual CLI commands.

Assigning an organization-level roles

The available organizational roles are: superuser, project-admin, billing-admin, and member. See Managing organization users.

An example of creating an OIDC group called akka-project-admins with a role of project-admin:

akka organization user add-binding --group akka-project-admins --role project-admin

Assigning a project-level role

The available project roles are: admin, developer, viewer and backoffice. A different command is used to create groups at the project level. See Managing project users.

An example of creating a group called akka-dev-admin with a role of admin that is then assigned to three different projects:

akka roles add-binding --group akka-dev-admin --role admin --project project1
akka roles add-binding --group akka-dev-admin --role admin --project project2
akka roles add-binding --group akka-dev-admin --role admin --project project3

An example of creating a group called akka-read-only with a role of viewer that is then assigned to two different projects:

akka roles add-binding --group akka-dev-admin --role viewer admin --project project1
akka roles add-binding --group akka-dev-admin --role viewer --project project2