Migrating to Indigo IAM πŸššοƒ

Starting with version 1.6.0, ska-aaa-authhelpers accepts access tokens issued by Indigo IAM in addition to Microsoft Entra ID. The SKAO-managed Indigo IAM instance is hosted at https://iam-1.staging.devx.skao.int/.

Important

As a service owner, you will need to:

  • Decide on a unique codename to represent your service in Indigo IAM.

  • Register your app’s scopes with Indigo IAM.

  • Update the audience field your service expects to reflect the new ID in Indigo alongside existing Entra ID identifiers.

Background

Indigo IAM is an open-source identity and access management service developed by the Italian research agency INFN and widely used at CERN. It is being adopted across SKAO as the core of our authorisation strategy. User and group management, role assignments, and client registrations for telescope applications will all live in Indigo IAM going forward.

Step 1: Decide on a codename for your service in Indigo IAM and register your app scopes.

You need to choose some unique name that refers to your application in SKAO authorisation contexts. This should be reasonably short but identifiable. For example, oet, pht, etc. Clients will request tokens to use with your service as either test:{codename} or live:{codename} depending on whether this is a production deployment.

Register each of your app’s existing scopes in Indigo, prefixed with your app codename, e.g. pht:read. You can log with an admin account at https://iam-1.staging.devx.skao.int/ or ask for assistance in the #help-aaa Slack channel. For more details, see the Indigo IAM documentation.

Step 2: Add the Indigo audience and scopes alongside your existing Entra ID values.

Update your Requires() (or functools.partial) to pass a tuple of both audience strings. Accepting both means that tokens from either issuer will be accepted, so existing Entra-authenticated clients keep working without any changes on their side.

import functools
from ska_aaa_authhelpers import Requires, Role

# These values come from your Entra registration (existing) and
# your new Indigo IAM codename:
ENTRA_AUDIENCE  = "3688e6c2-87c0-4584-a674-c11e63e9b442"
# Default to 'live' but override with `test:myapp` for non-prod
INDIGO_AUDIENCE = "live:myapp"

# Unless your scopes in Entra ID were already namespaced...
ENTRA_SCOPE = "read"
INDIGO_SCOPE = "myapp:read"

Permissions = functools.partial(
    Requires,
    audience=(ENTRA_AUDIENCE, INDIGO_AUDIENCE),
    scopes=(ENTRA_SCOPE, INDIGO_SCOPE)
)

None of the code inside your application should need to change β€” AuthContext normalises over the differences between Indigo IAM and Entra ID tokens, so any generic permission checks you have in place already should continue functioning identically.

Warning

The AuthContext.principals and AuthContext.groups properties will now contain names of Indigo IAM groups, rather than the IDs of Microsoft Entra groups. If your app logic relies on detecting particular group values, you will need to update it.

Step 3: Verify both varieties of token work

The test helpers support both issuers out of the box, but mint_test_token() produces Indigo-style tokens by default. To write tests that cover both paths:

from ska_aaa_authhelpers.jwt import DEFAULT_MS_ENTRA_ISS_V2
from ska_aaa_authhelpers.test_helpers import mint_test_token

# Indigo-style token (default):
indigo_token = mint_test_token(audience=INDIGO_AUDIENCE, scopes=["myapp:read"])

# Entra-style token (backwards-compatibility):
entra_token = mint_test_token(
    issuer=DEFAULT_MS_ENTRA_ISS_V2,
    scopes=["read"],
    audience=ENTRA_AUDIENCE,
)

See Testing your applications for more details on writing tests using this library’s test helpers.