External Users¶

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.

External users are authenticated external Identity Providers that issue JSON Web Tokens (JWT)¹ for their users.

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.

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.

1. IpUserId¶

If the user, which should be granted access, is strongly coupled to your services, use your userId as 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

PUT/Owners/{ownerAccountId}/IdentityProviders/{ipId}/Users

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

PUT/Owners/{ownerAccountId}/Contacts

operation.

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

GET/Owners/{ownerAccountId}/IdentityProviders/{ipId}/Users

operations can be used.

2. Identifier¶

With the combination of IpId and 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 ipId and identifier can be used to create a contact for the external user via the

PUT/Owners/{ownerAccountId}/Contacts

operation.