Ports and adapters

What this is about

CIAS writes a lot into the identity provider (IdP for short), that is, into Keycloak: accounts, organizations, roles, groups, attributes. Still, none of the business modules knows Keycloak. Registration does not know Keycloak’s URL, and role granting does not know how Keycloak stores a role.

That comes from a split into two parts:

• A port is a Java interface. It only says what is needed: “create an account”, “grant this role in this tenant”.
• An adapter is a class that fulfils this interface for one specific system. It knows how to do it in Keycloak: which HTTP call, which fields, which answer.

The picture

flowchart LR
    subgraph BM["Business modules"]
      R["cias-registration"]
      U["cias-user"]
      A["cias-authorization"]
    end
    subgraph P["cias-iam-api: ports"]
      P1["Accounts"]
      P2["Organizations"]
      P3["Roles"]
      P4["Groups"]
      P5["Attributes"]
    end
    R --> P
    U --> P
    A --> P
    P --> KA["cias-iam-keycloak<br/>Keycloak adapter"]
    P --> MA["cias-iam-memory<br/>in-memory adapter"]
    KA -- "Admin REST API" --> K["Keycloak"]
    MA --> M[("Memory<br/>in the process")]

Read it from left to right: the business modules only know the middle. On the right there is exactly one adapter, depending on the setting. The arrows only point in one direction. No business module goes past the middle to Keycloak. An architecture test in every business module checks this: a test that fails the build as soon as a class imports a Keycloak package.

The ports

There are eleven ports. Each one covers one capability, not a whole system. A module that only looks up addresses does not depend on role management.

Three terms from the table:

• A realm role applies in the whole realm and therefore in all modules, for example platform-admin. A client role belongs to one client and only means something there, for example a role of CDMS. See Realm role, client role, organization role.
• An organization is how Keycloak represents a dynamic tenant. See Static and dynamic tenants.
• The user profile is a document per realm in Keycloak that defines which attributes an account may have.

The rules behind the ports

The ports are cut this way on purpose. Each rule prevents a specific mistake.

• No Keycloak type in a port. No signature and no exception class names Keycloak. The port only knows its own small records such as NewIdentity or IamIdentity.
• No password. There is “require set password”, but no “set password”. CIAS never accepts a password.
• No user name. The email address is the login. One account per address, any number of tenants.
• Global and “in one organization” are separate methods. assign grants platform-wide, assignInOrganization only in one tenant. If both were one method with an optional tenant, a tenant administrator could give themselves platform-wide rights by accident.
• Realm roles and client roles are separate ports. For the same reason: through the port for client roles you cannot reach a realm role.
• Every call may come twice. Granting a role that is already there changes nothing. Enabling an account that is already enabled does not either. There is no shared transaction between CIAS and Keycloak. If an answer gets lost, repeating is the only way, and repeating must not break anything.
• A new capability is a new port. No catch-all interface with thirty methods.
• An attribute needs three steps, each in its own port. The profile allows it (UserProfileManagementPort), an account gets a value (IdentityAttributePort or at creation), and the value gets into the token (ClaimMappingPort). See The path into the token.

References instead of keys

Keycloak hands out its own IDs. CIAS keeps them in small wrappers: ExternalUserId, ExternalOrganizationId, ExternalGroupId, ExternalRoleId. These are only references: “this thing lives over there in the IdP”.

The business identity stays in CIAS:

So whoever replaces the IdP changes references, not data.

When Keycloak does not do something

Every port reports problems with one of four failure kinds. The business modules react to the kind, not to an HTTP status.

Lookups do not report “not found” as an error but as an empty result. “There is no account for this address” is the normal answer on a public endpoint.

Which adapter runs

Two things have to come together: the adapter’s jar is on the classpath, and the setting names it.

If both jars are on the classpath, still only the one the setting names runs. The standalone CIAS ships both: the local profile sets memory, everything else keycloak.

A second provider is a second artifact

If CIAS is ever to work with a different IdP, nobody changes the business modules. Instead, a new module is created, for example cias-iam-<name>:

Why a separate artifact and not a switch inside the Keycloak adapter? Every adapter brings the libraries of its IdP. If two IdPs lived in one module, every installation would depend on both. And the contract tests check exactly one adapter at a time.

Not every IdP can do everything. Organizations, roles in organizations or roles on groups are capabilities of Keycloak. An IdP without organizations cannot carry dynamic tenants.

Pitfalls

Next

• The Keycloak adapter
• The in-memory adapter for tests and development
• The Keycloak extension for the password link
• CIAS as a bridge to the identity provider