Login and Identity

Signing Workflow acts as a SAML Service Provider, which means that all identities are provided by an external source, the chosen SAML Identity Provider. Each actual person that has access to the system can be identified by potentially multiple IDs, e.g. email address, personal identity number, or a username.

In order to tie different user IDs, representing the same actual person, together, the Workflow service maps multiple external user IDs, given by the IdP OR the UserQuery service, to a single internal ID. That internal ID is used to bind activity in the system to a specific user.

The mapping from external IDs to an internal ID can be done on one of two possible occasions:

  1. The person logs in to the system. The Workflow service picks up the SAML NameID property and checks if there already exists a mapping for this ID. If not, a new mapping is created.
  2. The person is referenced in a request to create a new order. The request contains an identifier that uniquely identifies that particular person, when used for lookup in the UserQuery service. The lookup returns a list of IDs that the user may subsequently use for logging in to the system. Each of these IDs are checked to see if there is already an existing mapping. If there is no mapping, or if there are partial mapping to a single unique internal ID, the mapping is completed. If there are contradictory mappings, the system responds with an error, see below for how to fix it.

From the above it is clear that the UserQuery service and the IdP must make sure to use the same IDs to identify persons.

Internal and external users

A common use case for the Workflow service is to have two different groups of users: Internal users, i.e. users from the organization that owns the Workflow application, and External users, e.g. customers or regular citizens. These users are provided by different data sources, and searched using different sets of searchable properties. 

Internal users can be looked up using a number of different attributes: first name, last name, email address etc. Internal user search can return multiple results: for example, searching for first name Anders yields a list of all the persons in the organization whose name is Anders. It is also possible to use wildcard searches.

External users, however, can only be looked up using their Swedish personal identity number. Moreover, the match has to be exact: there can only be a single person with a specific identity number, and wildcard searches are not allowed.

In the following, the term query is used to for a search that might return 0, 1, 2 or more results, while the term lookup is used for a search that can only return 0 or 1 result.

Note that the terms Internal and External in this context refers to the user data sources, not to the internal IDs (provided by the Workflow service) and external IDs (provided by the IdP), see previous section.

Example

Anders Gran, and employee at ACME, is given signer access to the Workflow app and logs in to the system. The IdP sends his email address, anders.gran@acme.com, as NameID in the SAML ticket. Since no previous mapping exists for the given external ID (the email address), a new mapping is created:

external_id internal_id
INTERNAL:anders.gran@acme.com ca135746-bfeb-4790-bcd3-78e3b3fa1905

Later, Anders' colleague Anna Berg logs in to the system, with Solicitor permissions. She does a search for all employees at the workplace with first name Anders, and receives a list of several people. She selects Anders Gran as a signer.

She then searches for a person outside of the organization, using the Swedish personal identity number 860305-2385 and adds that person too as a signer.

Anna then submits the request to create a new order. The identifiers from the previous searches are used to execute a second lookup from the backend, uniquely identifying the persons she selected. These lookups provide two different login IDs that Anders might use: the email address and his Active Directory samAccountName agran, and the identity number for the other signer, but normalized to match  the NameID that the IdP will provide when the person logs in. The mapping table now looks like this (the prefixes INTERNAL and EXTERNAL refers to user data sources):

external_id internal_id
INTERNAL:anders.gran@acme.com ca135746-bfeb-4790-bcd3-78e3b3fa1905
INTERNAL:agran
ca135746-bfeb-4790-bcd3-78e3b3fa1905
INTERNAL:anna.berg@acme.com a72236a9-d946-4c24-acce-65c9e54c9945
EXTERNAL:198603052385
b80af041-12b9-47c9-a765-b9e7d9451785

When the signers logs in to the Workflow application, using any of the values in the external_id column as user ID, the internal_id for respective user is used to lookup the corresponding activity in the system and find the order that Anna created.

Below is a sequence diagram, outlining the described Create Order process.

Trouble shooting

There are a few situations when user ID mapping might go wrong, depending on how the system is configured.

Possible errors

Suppose that the UserQuery service is configured to return Active Directory samAccountName as the only possible login ID. When a CreateOrder request is submitted, a new internal ID is created and mapped to the samAccountName of the user.

Now suppose that the IdP is configured to use the email address as SAML NameID. When the signer logs in, the previously created order is not visible, since that order is mapped to the samAccountName. A new internal ID is created and mapped to the email address.

There are now two different internal IDs in the system, but they are referring to the same actual person! If the UserQuery service is now re-configured to return both email address and samAccountName as possible login IDs, another problem emerges: when a solicitor tries to create an order, selecting that person as a signer, the Workflow service will detect that the two login IDs provided are actually already mapped but to different internal IDs. The system will then refuse to create the order, since the intended receiver cannot be uniquely determined.

The same situation could arise if the IdP is configured to accept multiple login IDs, and returns different NameID values for the same person, depending on the choice of login ID. If there is no previous login mapping in the system, each NameID will be mapped to different internal IDs when the user logs in, and the same problem will occur when a Solicitor is trying to create an order, referencing this person.

How to fix

If the situation described above arises, the solution is to find the external IDs in the mapping table, and assign them the same internal ID. In the example above, the mapping table might look like this:

external_id internal_id
INTERNAL:anders.gran@acme.com ca135746-bfeb-4790-bcd3-78e3b3fa1905
INTERNAL:agran 4b4fd1fb-4964-4465-9885-ae73999545eb

Find out which internal ID is mapped to the order activity in the Workflow system, then reassign the values accordingly:

external_id internal_id
INTERNAL:anders.gran@acme.com
ca135746-bfeb-4790-bcd3-78e3b3fa1905
INTERNAL:agran ca135746-bfeb-4790-bcd3-78e3b3fa1905