Identity Governance & Administration
sara.next
  1. sara.next
  2. Technology
  3. Building an adapter

Technology · For developers

Building an adapter

An IGA adapter should not just "call an API". It must safely translate an approved business decision into a verifiable change of permissions.

  • REST
  • SQL
  • Groovy
  • idempotency
  • verification

Context

When an adapter is needed

sara.next centralises the access management process, but target resources differ in account format, roles and integration methods. For one application a REST call is enough, for another a write through a controlled SQL interface, and for a legacy system manual execution by an implementer. An adapter is a translation layer between the request model and the specifics of the target system.

NoteThe sara.next documentation describes direct auto-implementation through configured REST/SQL connections and Groovy scripts. It does not include a universal public SDK or a single binding "adapter contract" made available to all partners.

If a team builds a separate adapter service, its interface should be designed and agreed in the project.

Process

Stages of building an integration

  1. Permission inventory

    Account identifier, roles, groups, scopes (dimensions), resulting permissions and dependencies.

  2. Mapping operations

    create, modify, replace, delete, as well as reading the state for verification.

  3. Decision rules

    Specify when access can be changed and when it has to be blocked or referred back to the application owner.

  4. Connection

    Choose REST or SQL according to the documented auto-implementation method; the connection must have minimum permissions.

  5. Validation and testing

    Check dictionaries, identifiers, allowed values and conflicting assignments.

  6. Verifying the result

    Confirm the actual target state, not just the HTTP status or the successful execution of SQL.

  7. Failure handling

    Plan how to distinguish a permanent error from a temporary one and a safe way to resume the process.

Design example

A logical contract — a design example, not the public sara.next API

{
  "requestId": "IGA-2026-00125",
  "operation": "grant",
  "subject": "user-1234",
  "targetSystem": "finance-app",
  "entitlement": "invoice-read",
  "scope": { "company": "PL01" },
  "approvedAt": "2026-11-15T10:00:00Z"
}

This is a sample internal logical contract that makes the conversation with the integration team easier; it should not be treated as a ready-made payload supported by the product.

The actual sara.next fields are available through script variables, including user, oldUser, role, dimensions, request, application.

Options

Choosing the implementation model

Choosing the implementation model
OptionWhen to use itMain consequence
Direct RESTThe system has a controllable API for managing permissionsMaintaining the mapping of endpoints and authorisation
Direct SQLNo API, but the vendor allows controlled DB integrationHigh requirements regarding the scope of permissions and compatibility with the DB model
Dedicated adapter microserviceComplex rules, several endpoints, asynchrony or a separate permission domainAn additional component to maintain, monitoring and an API contract
Manual implementerAn isolated system or no safe automation pathLonger completion time, the need for independent control of execution

Verification

Correctly reading the target state

An adapter should not consider a grant operation successful just because the server returned 200 or 204. Some APIs perform operations asynchronously, and some return a correct response even though the expected role membership is missing. Verification should read the specific role assignment in the appropriate scope and handle eventual consistency. When verification requires additional rules, they should be agreed in the script or adapter code.

sara.nextScript / adapterTarget system01 Approved change: grant02 Permission change request03 Response 200 or 20404 Reading the role assignment in scope05 Actual target state06 Verification result
Illustrative diagram. A 2xx response alone does not confirm that the permission exists.

An implementation expert's view

A successful integration is consistency after a retry and a timeout

I consider an integration successful not when it can grant access in a demo, but when it stays consistent after repeated operations, timeouts and a change of role scope.

Most production problems are caused by poorly defined replace and modify semantics: removing an old permission does not always mean that the account or the user's whole group of permissions can safely be removed.

Acceptance

What we require when accepting an adapter

Error and exception handling

Scope of acceptance tests

  • positive tests of all operations
  • access denial test
  • invalid identifier test
  • timeout
  • retrying an identical request
  • missing technical account permissions
  • a divergent state before and after the operation
  • log correlation
  • a procedure for manually restoring consistency

Discuss the permission model of the target system

We will choose the safest integration option for your application.