If your app is using an OIDC authentication flow, it is possible to integrate Tanker's identity verification with this flow. Doing this will make the identity verification completely invisible to the end-user.

Warning

The OIDC verification method is still under development and is provided as a preview version only.

Prerequisite: configuring your Tanker App

Warning

For now, the only supported OpenID Provider is Google.

If needed, follow the instructions on the Google OpenID Connect documentation to get a Client ID.

When ready, go to the dashboard and register your Google OpenID Connect Client ID on the desired Tanker App.

Setting up a verification with OpenID Connect

Setting up a user with OpenID Connect is done by using the registerIdentity() method with the oidcIdToken argument.

if (status == Status.IDENTITY_REGISTRATION_NEEDED) {
  // Get an OIDC ID Token from Google for the current user
  String googleIdToken = app.getGoogleIdToken();
  Verification verification = new OIDCIDTokenVerification(googleIdToken);
  tanker.registerIdentity(verification).get();
}

if (status == TKRStatusIdentityRegistrationNeeded) {
  // Get an OIDC ID Token from Google for the current user
  NSString* googleIdToken = [self.app getGoogleIdToken];

  TKRVerification* verification = [TKRVerification verificationFromOIDCIDToken:googleIdToken];
  [self.tanker registerIdentityWithVerification:verification
                              completionHandler:^(NSError* err) {
                                if (err == nil) {
                                  // do something
                                }
                              }];
}

if (status === Tanker.statuses.IDENTITY_REGISTRATION_NEEDED) {
  // Get an OIDC ID Token from Google for the current user
  const idToken = await app.getGoogleIdToken();

  // Register the identity with OIDC
  await tanker.registerIdentity({ oidcIdToken: idToken });
}

Verifying the identity with OpenID Connect

To later verify the user's identity with OpenID Connect, pass the oidcIdToken argument to verifyIdentity() after starting the session:

if (status == Status.IDENTITY_VERIFICATION_NEEDED) {
  // Get an OIDC ID Token from Google for the current user
  String googleIdToken = app.getGoogleIdToken();
  Verification verification = new OIDCIDTokenVerification(googleIdToken);
  tanker.verifyIdentity(verification).get();
}

if (status == TKRStatusIdentityVerificationNeeded) {
  // Get an OIDC ID Token from Google for the current user
  NSString* googleIdToken = [self.app getGoogleIdToken];

  TKRVerification* verification = [TKRVerification verificationFromOIDCIDToken:googleIdToken];
  [self.tanker verifyIdentityWithVerification:verification
                            completionHandler:^(NSError* err) {
                              if (err == nil) {
                                // do something
                              }
                            }];
}

if (status === Tanker.statuses.IDENTITY_VERIFICATION_NEEDED) {
  // Get an OIDC ID Token from Google for the current user
  const idToken = await app.getGoogleIdToken();

  // Verify the identity with OIDC
  await tanker.verifyIdentity({ oidcIdToken: idToken });
}

To update a user's OIDC verification method, just call setVerificationMethod() with a new oidcIdToken.

Security considerations

The terminology used in this section comes from the OAuth 2.0 RFC and the OpenID Connect Spec.

Here are a few requirements for the OIDC verification method to be used safely:

  1. The Client must never use the ID Token to authenticate users or give them access to any resource (including Tanker identities), otherwise Tanker could impersonate users on the Client side.
  2. The Client must never request a Refresh Token with the openid scope. Otherwise, the Client would be able to request a new ID Token and proceed to Tanker identity verifications, even when the user is offline.
  3. The ID Token must never be persisted by the Client, even in volatile memory. Before its expiration, an unduly persisted ID Token would remain available for use, even after the user has disconnected from the Client. The Client servers having access to the Tanker identities, the Client would be able to proceed to Tanker identity verifications without user consent.