sym.sdk.strategies¶

Modules

`sym.sdk.strategies.access_strategy`
`sym.sdk.strategies.integration`

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 and ExceptionWithHint.

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() on event. 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 or None 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 and ExceptionWithHint.

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() on event. It also contains other useful values; see the docs for Event.

Returns

An optional dictionary of state that should be preserved for de-escalation. This can be accessed in deescalate() by calling get_step_output() in the implementation there. This value is also made available to Hooks in Flow implementations, also via get_step_output(). This method can also return an empty dict or None 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 that get_requester_identity() will raise an IdentityNotFound 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 calling fetch_remote_identity() as needed.

This method is meant to be called in implementations of the AccessStrategy class; e.g., escalate() and deescalate(), 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() returned None)

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 the external_id.

property name¶: An alias for this resource’s slug, derived from its SRN.

property settings¶: A dictionary of settings for the Integration, as specified in Terraform. May be empty, but will never be None.

property srn¶: A SRN object that represents the unique identifier for this resource.

property type¶: The type of service represented by this Integration object.