How to setup a Microsoft Azure AD, Avassa integration

This how-to describes how to configure Azure AD as an OIDC provider for a tenant in an Avassa system. This means that users in this tenant will authenticate through the existing AD, and no need to add users to the Avassa system. The steps are:

• Create a new tenant
• Adds Azure AD as an OIDC provider

Prepare Azure AD

We need to prepare our Control Tower as an OIDC client in Azure AD. All this configuration is done in the Azure Active Directory configuration.

Click New registration

NOTE: Make sure you add a redirect URI here, the path is: <env-name>.<org-name>.avassa.net/oidc-callback

After saving, you will see something like this, make a note of the Application (client) ID

Next create a new secret by clicking Client credentialsand add a client secret.

Note the Value of the secret.

Next select client Endpoints here:

And note OpenID Connect metadata document

Add user groups as a claim

For this tutorial, we will map Azure AD groups to policies in the Avassa System. To add groups as a claim, select the app registration and add groups claim:

Azure AD Information

You should now have the following values from Azure:

client ID	dd3ef79f-b9b4-44bd-b1ec-e71b221e0e96
client secret	LCq8Q~lls7H4AYpD-J2~dI1BjumZbbET8GXincAx
Discovery URL	https://login.microsoftonline.com/05289459-ce92-4e14-ad0d-36873f30981a/v2.0/.well-known/openid-configuration

Configure OIDC for a tenant in Avassa

Now, over to the Avassa system.

First, we will create a new tenant, in this example we will call this tenant popcorn-inc.

supctl -d .supctl replace tenants popcorn-inc <<EOF
name: popcorn-inc
kind: application-owner
policies:
  - app-owner-tenant
EOF

Next, we will generate a root token for this tenant. NOTE: This can only be done once, so make sure you keep track of this token

supctl -d .supctl do strongbox token create-root --name popcorn-inc
Warning: Providing --name on the command line is insecure. Consider using --name-prompt instead.
{
  "accessor": "c51e2c8d-1cab-4d36-9880-294bc5529059",
  "token": "6c1fa04e-463a-4e61-bcc9-fd1e072f16cc",
  "creation-time": "2023-01-16T11:36:10.549630Z"
}

With the discovery URL, client ID and the secret from above, we can now create the oidc service.

NOTE 1: make sure allowed-redirect-uris match what you configured in Azure above.

NOTE 2: role-claim: groups will try to match all group names in the groups to oidc roles.

supctl -t 6c1fa04e-463a-4e61-bcc9-fd1e072f16cc -d .supctl replace strongbox authentication oidc-services azure-ad <<EOF
name: azure-ad
display-name: azure-ad
discovery-url: [<https://login.microsoftonline.com/05289459-ce92-4e14-ad0d-36873f30981a/v2.0/.well-known/openid-configuration>](<https://login.microsoftonline.com/05289459-ce92-4e14-ad0d-36873f30981a/v2.0/.well-known/openid-configuration>)
use-root-ca-certs: true
client-id: dd3ef79f-b9b4-44bd-b1ec-e71b221e0e96
client-secret: LCq8Q~lls7H4AYpD-J2~dI1BjumZbbET8GXincAx
verbose-logging: true
role-select:
  role-claim: groups
  allowed-redirect-uris:
    - <https://azure.the-company.avassa.dev/oidc-callback>
EOF

Now we will create OIDC roles to match an Azure groups. Azure groups are sent in the form of GUIDs, you can find the roles in azure in the Groups menu, there the group names and guid (Object Id) are listed.

Here we match the dbb4bd8f-c8a9-45c1-a6d2-5456f2fcb6b9 group id to a root policy.

supctl -t 6c1fa04e-463a-4e61-bcc9-fd1e072f16cc -d .supctl create strongbox authentication oidc-services azure-ad roles <<EOF
name: dbb4bd8f-c8a9-45c1-a6d2-5456f2fcb6b9

# These are optional mappings
claim-mappings:
  email: email
  name: username

# Map this group to the following policies
token-policies:
  - root
EOF

Test AD login

To login, go to your environment and click change tenant

Click get login options and then login with azure-ad.

At this point you will be redirected to Azure and after logging in redirected back into Control Tower.

Now you can manage all your users in Azure AD and map Azure groups to policies in Control Tower. Adding new users to Control Tower is a matter of assigning them the right groups in the AD.