# Migrating to Indigo IAM 🚚

Starting with version 1.6.0, `ska-aaa-authhelpers` accepts access tokens issued by
[Indigo IAM](https://indigo-iam.github.io) 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](https://home.infn.it/it/) 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](https://indigo-iam.github.io/v/v1.14.1/docs/reference/configuration/system-scopes/).

## 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.

```python
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`](components.md#authcontext) and [`AuthContext.groups`](components.md#authcontext) 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:

```python
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](testing.md) for more details on writing tests using this library's test helpers.