- sara.next
- Technology
- 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
Permission inventory
Account identifier, roles, groups, scopes (dimensions), resulting permissions and dependencies.
Mapping operations
create,modify,replace,delete, as well as reading the state for verification.Decision rules
Specify when access can be changed and when it has to be blocked or referred back to the application owner.
Connection
Choose REST or SQL according to the documented auto-implementation method; the connection must have minimum permissions.
Validation and testing
Check dictionaries, identifiers, allowed values and conflicting assignments.
Verifying the result
Confirm the actual target state, not just the HTTP status or the successful execution of SQL.
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
| Option | When to use it | Main consequence |
|---|---|---|
| Direct REST | The system has a controllable API for managing permissions | Maintaining the mapping of endpoints and authorisation |
| Direct SQL | No API, but the vendor allows controlled DB integration | High requirements regarding the scope of permissions and compatibility with the DB model |
| Dedicated adapter microservice | Complex rules, several endpoints, asynchrony or a separate permission domain | An additional component to maintain, monitoring and an API contract |
| Manual implementer | An isolated system or no safe automation path | Longer 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.
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.
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.