Tapkey enables third-party services to use their own existing users for utilizing Tapkey Web APIs or the Tapkey Mobile SDK. When it comes to the Tapkey Mobile SDK, external users are required to be authenticated via an Identity Provider.
This section aims to provide an overview of how authentication for external users with Tapkey works.
Authenticating External Users¶
1. Issue a JWT¶
The third-party Identity Provider creates a signed JWT that contains information about the authenticated user, like the userId specific to the Identity Provider.
For more information about the structure of JWTs compatible with Tapkey, as well as for implementation and configuration of an Identity Provider, refer to Identity Providers.
2. Exchange against a Tapkey Access Token¶
The client app exchanges the JWT provided by the external Identity Provider for a Tapkey Access Token using the Token Exchange Flow.
3. Use the Tapkey Access Token¶
The Tapkey Access Token can then be used to authenticate calls to the Tapkey Web APIs or to perform a login with the Tapkey Mobile SDK.
sequenceDiagram participant APP as Client App participant IP as Identity Provider participant TTS as Tapkey Trust
Services note over APP, TTS: Authenticate against
Identity Provider to retrieve JWT APP->>+IP: Authenticate IP->>IP: Sign JWT IP-->>-APP: JWT note over APP, TTS: Exchange JWT for Tapkey Access Token APP ->>+ TTS: Exchange Token TTS -->>- APP: Tapkey Access Token Note over APP,TTS: Use Tapkey Access Token for authenticated API requests alt Use Tapkey Web API APP ->>+ TTS: Use Tapkey Access Token to authenticate Web API requests TTS -->>- APP: result else Log in into Tapkey Mobile SDK APP ->> APP: Use Access Token
to perform a login with the Tapkey Mobile SDK end
Granting access to external Users¶
When creating a grant for users, it is required to address the correct user. Tapkey uses three attributes to describe a user uniquely.
|IpId:||The Id of the used Identity Provider. Will be generated when registering the Identity Provider.|
|Identifier||A distinct identifier of the users within the Identity Provider choice like an email, a phone number, a booking number etc. It will be derived from a certain claim of the issued JWT and used for identifying a user when a grant is created.|
Depending on the requirements of the target service, two different ways of addressing external users exist. They are mutually exclusive and must be configured upfront during the initial setup of the Identity Provider.
If the user, which should be granted access, is strongly coupled to your services, use your
ipUserId to map the user.
For example, let's imagine a big car rental service. The rental service already offers an app where users can sign up, upload their driver's license and book a car. From that point on, using Tapkey, the rental service is only one step away from unlocking cars via their app:
sequenceDiagram participant U as User participant A as Client App participant S as Rental Service participant T as Tapkey Trust
Services note over U,T: Client App Login U ->>+ A: Login A ->>+ S: Authenticate as User "u1" opt User "u1" was not created yet Note over S,T: A user has to be explicitly
created at Tapkey S ->>+ T: Create User with ipUserId "u1"
and ipId of registered Identity Provider T -->>-S: ok end S->>S: Sign JWT S -->>- A: JWT A->>+T: Exchange JWT for Tapkey Access Token T-->-A: Tapkey Access Token A->>A: Use Access Token to perform a
login with the Tapkey Mobile SDK A -->>- U: ok note over U,T: Granting Access U ->>+ A: Book Car "Van1" A ->>+ S: Book Car "Van1" opt Contact was not created yet S ->>+ T: Create Contact with ipUserId "u1"
and ipId of registered Identity Provider
for Owner of "Van1" T -->>- S: Contact end S ->>+ T: Grant Contact to access Lock "Van1" T -->>- S: Grant S -->>- A: ok A -->>- U: Car "Van1" is booked note over U,T: Mobile Key Handling
(happens in background) alt Push Notification is Configured T ->> A: New Mobile Key available A ->>+ T: Get Mobile Keys T -->>- A: Mobile Key for lock "Van1" else Regular or explicit polling A ->>+ T: Are new Mobile Keys available? T -->>- A: Yes A ->>+ T: Get Mobile Keys T -->>- A: Mobile Key for lock "V1" end note over U,T: Opening Car U ->>+A: Open Car "Van1" opt Mobile Key has not been fetched yet A->>+T: Get Mobile Key for lock "Van1" T-->>-A: Mobile Key for lock "Van1" end A ->> A: Unlock Lock "Van1" A -->>-U: Car is opened
As illustrated in the sequence diagram above, the rental service is in charge of creating users on Tapkey side, authenticating them in their client app and granting them access to Tapkey locking devices. It is just obvious to map users via their original user id.
To grant access to users via
ipUserId, the user must be registered with Tapkey using the
operation before they can interact with Tapkey.
To create a new user, the user's external ID (Identity Provider user ID) as well as the Identity Provider's ID will be passed to Tapkey. Tapkey will issue an internal ID for that user (Tapkey user ID).
The combination of Identity Provider ID and Identity Provider user ID can be used to create a contact for the external user via the
To list all users of an Identity Provider that are registered with Tapkey, or to retrieve single users by either Tapkey user ID or Identity Provider user ID, the
operations can be used.
With the combination of
identifier, your users can be addressed with a distinct but understandable identifier like email, phone numbers or other identifiers.
This is beneficial when the granting and granted parties are loosely coupled and the Identity Provider's internal user id is not necessarily known during granting access. Think about a hospitality platform and a branded app to unlock the booked room via a phone number.
sequenceDiagram participant A as Host participant B as Guest participant S as Hospitality Platform participant APP as Client App participant IP as IdentityProvider participant TTS as Tapkey Trust
Services note over A,TTS: Granting Access A ->>+S: Grant phone number "+5512345" access
to Room "R1" note over S,TTS: When using an identifier, creating a user upfront
is not required opt Contact was not created yet S ->>+ TTS: Create Contact for identifier: "+5512345",
with ipId of Identity Provider
for owner of lock "R1" TTS -->>- S: Contact end S ->>+TTS: Grant Contact
to access lock "R1" TTS -->>-S: Grant S -->>-A: ok note over A,TTS: Client App Login B ->>+APP: Use phone number "+5512345"
to log in APP->>+IP: Authenticate phone number "+5512345" IP->>IP: Sign JWT IP-->>-APP: JWT APP->>+TTS: Exchange JWT for Tapkey Access Token TTS-->-APP: Tapkey Access Token APP->>APP: Use Access Token
to perform a login with the Tapkey Mobile SDK APP->>-B:ok note over A,TTS: Mobile Key Handling
(happens in background) alt Push Notification is configured TTS ->> APP: New Mobile Key available APP ->>+ TTS: Get Mobile Keys TTS -->>- APP: Mobile Key for lock "R1" else Regular or explicit polling APP ->>+ TTS: Are new Mobile Keys available? TTS -->>- APP: Yes APP ->>+ TTS: Get Mobile Keys TTS -->>- APP: Mobile Key for lock "R1" end note over A,TTS: Unlocking Room B ->>+APP: Unlock Room "R1" opt Mobile Key has not been fetched yet APP->>+TTS: Get Mobile Key for lock "R1" TTS-->>-APP: Mobile Key for lock "R1" end APP ->> APP: Unlock lock "R1" APP -->>-B: ok
As shown by the sequence diagram above, the hospitality platform and the app are operating completely independently. The platform is not connected to the Identity Provider and has no access to its list of users.
In this case, it makes sense to use the distinct phone number to identify the external user.
The combination of
identifier can be used to create a contact for the external user via the