sym.sdk.strategies¶
Modules
Classes for representing Strategies and Integrations, including fully custom Strategies.
- class sym.sdk.strategies.AccessStrategy(integration: sym.sdk.strategies.integration.Integration)¶
A standardized interface that allows Implementers to define custom Strategies, enabling Sym to perform escalations and de-escalations against almost any Internet-accessible service.
- deescalate(target_id: str, event: sym.sdk.event.Event) Optional[dict] ¶
Perform a de-escalation in the external service.
This method is called to perform de-escalations, and should implement all functionality needed to revoke access granted by this strategy’s
escalate()
method. For example, an implementation of this method might construct a JSON request body and then submit an HTTP DELETE request to some REST API endpoint.This method should be idempotent; de-escalating the same user and target pair multiple times (or calling this method on a user who is not escalated at the time of the call) must not cause an error. However, errors may be reported by simply raising an exception; these exceptions will be handled by Sym’s built-in error handling logic. If you wish to implement your own exceptions, please refer to
SymException
andExceptionWithHint
.- Parameters
target_id – The ID of the “target” of the de-escalation, which can be thought of what the user is being removed from for de-escalation. Specified by the Implementer in Terraform, and often was selected by the requesting user when making the request; will be the same value as was passed to
escalate()
event – A representation of the de-escalation event. The ID of the user being de-escalated can be retrieved by calling
get_requester_identity()
onevent
. It also contains other useful values; see the docs for Event.
- Returns
An optional dictionary of state that should be made available to Hooks in Flow implementations via
get_step_output()
. This method can also return an empty dict orNone
to indicate that nothing needs to be preserved for Hooks. Failure must be indicated by raising an exception.
- escalate(target_id: str, event: sym.sdk.event.Event) Optional[dict] ¶
Perform an escalation in the external service.
This method is called to perform escalations, and should implement all functionality needed to grant access to a user for a resource. For example, an implementation of this method might construct a JSON request body and then submit an HTTP POST request to some REST API endpoint.
This method should be idempotent; escalating the same user and target pair multiple times must not cause an error. However, errors may be reported by simply raising an exception; these exceptions will be handled by Sym’s built-in error handling logic. If you wish to implement your own exceptions, please refer to
SymException
andExceptionWithHint
.- Parameters
target_id – The ID of the “target” of the escalation, which can be thought of what the user is being escalated to. Specified by the Implementer in Terraform, and often selected by the requesting user when making the request.
event – A representation of the escalation event. The ID of the user being escalated can be retrieved by calling
get_requester_identity()
onevent
. It also contains other useful values; see the docs forEvent
.
- Returns
An optional dictionary of state that should be preserved for de-escalation. This can be accessed in
deescalate()
by callingget_step_output()
in the implementation there. This value is also made available to Hooks in Flow implementations, also viaget_step_output()
. This method can also return an empty dict orNone
to indicate that no special state needs to be preserved for de- escalation or Hooks. Failure must be indicated by raising an exception.
- fetch_remote_identity(user: sym.sdk.user.User) Optional[str] ¶
Fetches the external identity of the requester from the remote service; not meant to be called directly.
This method is used to fetch the external identity of the requester when Sym does not already have that information available. Commonly, this is when a user makes a request utilizing a given
Integration
for the first time.This method should return a string that represents the user’s unique user ID in the service this Strategy interacts with; or, more specifically, whatever is needed to identify the user being escalated or de-escalated in the service that is performing the escalation/ de-escalation. The user ID value can be any string; it is treated as an opaque value by the Sym platform. For example, if the Strategy were interacting with AWS IAM, the user ID returned by this method would be the user’s ARN.
If the user’s identity cannot be fetched, or this automated remote identity discovery does not need to be implemented, this method may return
None
instead; however, note thatget_requester_identity()
will raise anIdentityNotFound
exception if the requester does not already have an identity.To be clear, this method does not need to be implemented in situations where there is no need to maintain a mapping of users to external identities; for example, if the user’s email address, which is already captured by Sym, is all that is needed by the external service.
Implementers should not call this method directly; instead, use
get_requester_identity()
, which calls this method as needed.If this method returns a non-
None
value,get_requester_identity()
will persist the value to the user saved in Sym so that this lookup doesn’t need to be performed again.- Parameters
user – The user to fetch an external service identity for
- Returns
An opaque string value representing the user’s unique identifier in the external service, or
None
if this lookup should not or cannot be performed.
- final get_requester_identity(event: sym.sdk.event.Event) str ¶
Retrieves the external identity of the user who initiated the request represented by the
event
parameter; first from stored user information, then by callingfetch_remote_identity()
as needed.This method is meant to be called in implementations of the
AccessStrategy
class; e.g.,escalate()
anddeescalate()
, as a way to resolve the mapping of a Sym user to their corresponding identity in the external service being interacted with.To be clear, this method does not need to be called in situations where there is no need to maintain a mapping of users to external identities; for example, if the user’s email address, which is already captured by Sym, is all that is needed by the external service.
This method’s source can also be used as a reference for how the external identity lookup process works. It should not be overridden!
- Parameters
event – An object containing information about the current event
- Returns
The unique identifier for the user who initiated the request, for the external service being interacted with.
- Raises
IdentityNotFound – If the user has no identity mapping configured and it could not be looked up (
fetch_remote_identity()
returnedNone
)
- class sym.sdk.strategies.Integration(srn: Union[sym.sdk.resource.SRN, str])¶
Bases:
sym.sdk.resource.SymResource
Represents an Integration (service-specific config and state) in the Sym SDK.
For the purposes of the SDK, Integrations can be thought of as the “state” of a Strategy. Or, to put it another way, if a Strategy tells Sym how to interact with an external service to perform escalations, the Integration is the service-specific state Sym maintains, including the identity mappings of Sym users to the external service.
- dict()¶
Represent this resource as a dictionary.
- property external_id¶
A unique (for this type), meaningful identifier for this Integration.
This allows you to have multiple integrations of the same type. The meaning of the
external_id
varies from Strategy to Strategy—some Strategies use this as a domain or tenant identifier for some services, while for others it’s simply an Implementer-defined identifier.For example, a Slack Integration uses the Slack workspace ID as the
external_id
value, while an Okta Integration uses the Okta Domain as theexternal_id
.
- property settings¶
A dictionary of settings for the Integration, as specified in Terraform. May be empty, but will never be
None
.
- property type¶
The type of service represented by this Integration object.