Overview

When a Sym user makes a request for the first time, we have one piece of identity about them: their email address. Usually, this is enough information to do a lookup in any third-party target service (e.g. Okta), find, and persist a third-party identity. Put otherwise, in common circumstances, access requests from Sym will "Just Work" for a majority of users.

Sometimes, a user's Sym and target service emails won't match – and that's ok, too, because Sym provides multiple ways of solving for identity, both individually, and at scale.

How Sym handles identity

Sym manages identity any time a user needs to be escalated, or a call is made from the Sym SDK that requires checking or using a third-party identity. For example, if a Flow has a Hook that checks PagerDuty for on-call status, we'll need to discover and check against a user's PagerDuty identity any time that flow is run.

Sym goes through the following process, in order.

Is there an identity?

First, we'll check if an identity has already been stored for the User:Service pair. If an identity exists, good news! The Flow continues, and all is well. If not...

Is there a get_identity reducer in place?

If an identity does not exist, Sym will check for a get_identity Reducer in the Flow's Python implementation. If the Reducer includes a mapping rule for the target service, Sym will run it, and if it hits on an identity, will persist it for that user. If not...

🚧

get_identity does not work with Custom Strategies

Sym's Custom Strategy framework supports a separate fetch_remote_identity method for mapping and persisting identities. For building fully custom strategies outside of Sym's native integrations, please refer to the guide linked above, and the SDK docs here.

Does the Sym email match an identity?

If there is no get_identity reducer or there is, but no match is found, Sym will call the target service and use the user's Sym email as a lookup key. This is the most common scenario.

Manual mapping

Finally, if none of the above manage to land on a viable identity, Sym will throw an error, and the user must be mapped manually using the symflow CLI.

📘

Note: once a user identity has been persisted, the symflow CLI is the only way to manually remove or overwrite the stored identity.