OpenID Connect (OIDC) is a popular client authentication mechanism supported by Couchbase Sync Gateway.

In this context, clients may be Couchbase Lite clients that synchronize data with Sync Gateway over the Internet using the websockets-based replication protocol or they could be web frontend or mobile apps accessing Sync Gateway through the public REST endpoint.

Last week, we discussed the fundamentals of OIDC and OAuth2 flows. In this week’s blog post, I’ll introduce you to OIDC Implicit Flow-based client authentication within the context of Couchbase Sync Gateway replication. This post assumes familiarity with OIDC and OAuth2 flows for authentication and authorization. So if you are unfamiliar with the flows or need a refresher, definitely catch up with last week’s blog post.

Couchbase Sync Gateway OIDC Configuration

 

On a per database basis, Couchbase Sync Gateway must be configured for OIDC authentication.

Here is a basic config for Implicit Flow. (Refer to the official documentation pages for a complete listing of all config options.)

 

    • issuer is the authentication URL corresponding to the OIDC identity provider
    • client_id is generated as part of the app registration process with the OIDC provider. The client here refers to the Couchbase Lite app or web app. Note that client_id does not correspond to the end user of the app who is technically the “Resource Owner”.
    • The register flag, if set to true, will result in the user being automatically created on the Sync Gateway following successful ID token validation.
    • username_claim corresponds to the JWT claim to be used as the Sync Gateway username. By default, the Sync Gateway username would take the form issuer+subject where issuer refers to the username prefix. The prefix value defaults to the issuer claim and can be configured to use a different claim value via the user_prefix config option.

 

Couchbase Sync Gateway OIDC Discovery

 

On startup, the Sync Gateway connects to the discovery endpoint associated with the configured OIDC provider/issuer to fetch relevant provider metadata. The metadata includes relevant information required for token validation such as issuer public keys, supported encryption algorithms used for encoding the claims in the ID token, etc.

The discovery endpoint corresponds to a well-known discovery URL associated with the issuer. If needed, one can override that via the Sync Gateway discovery_url config option.

OIDC Implicit Flow for Client Authentication

 

This flow is based on the standard OIDC Implicit Flow discussed in the OIDC basics blog. It is simpler than the alternate Authorization Code flow-based approach and is generally the preferred approach for Sync Gateway OIDC client authentication.

Implicit Flow using Bearer Token

 

In this flow, Couchbase Lite clients embed the ID Token retrieved from the OIDC Provider (OP) as the Bearer token within the Authorization header during initialization of replication.


OpenID Connect Implicit Flow using session ID

  1. When a user logs into the Couchbase Lite client app, the client initiates OIDC implicit flow with the OIDC Provider to retrieve the ID token. This is per standard OIDC flow procedures outlined in the OIDC basics blog.
  2. The client app initiates a replication using the ID token as the Bearer token in the HTTP Authorization Header.
  3. Sync Gateway validates the ID token locally. Following successful token validation, a corresponding UserCtx object is created.
    • The metadata retrieved from the OIDC Provider Discovery URL during startup is used to validate the token in “offline mode”.
    • If this is the first time that the user is authenticating with the Sync Gateway and if a corresponding user does not exist on the server, the Sync Gateway automatically creates a user if the “register” config option is set to true.
      • Note: The user that is created is not associated with any access grants such as channels or roles. This auto-registration would only work for public users with no user-specific access grants. We will discuss a flow later in this post that describes how to create users with user-specific access grants.
  4. Following successful initialization, replication proceeds as usual and document changes on the client app and Sync Gateway side are synchronized.
    • If the user is deleted during an active replication, the replication is terminated.
    • If the access grants associated with the user have changed, then documents that get impacted by the updated access grants won’t be replicated. For instance, if a user loses access to a channel, then the documents in that channel won’t be pulled.

 

Implicit Flow Using Session ID

 

In this flow, Couchbase Lite clients embed the session ID generated by the Sync Gateway following successful ID Token validation as a session cookie during initialization of replication.

OpenID Connect Implicit Flow using a bearer token


  1. When a user logs into the Couchbase Lite client app, the client initiates OIDC Implicit flow with the OIDC Provider to retrieve the ID token. This is per standard OIDC flow procedures outlined in the OIDC basics blog.
  2. The client app creates a session using the session REST endpoint. The ID token is set as the Bearer token in the HTTP Authorization Header.
  3. Sync Gateway validates the ID token locally. Following successful token validation, a corresponding UserCtx object is created.
    • The metadata retrieved from the OIDC Provider Discovery URL during startup is used to validate the token in “offline mode”.
    • If this is the first time that the user is authenticating with the Sync Gateway and if a corresponding user does not exist on the server, the Sync Gateway automatically creates a user if the register config option is set to true.
      • Note: The user that is created is not associated with any access grants such as channels or roles. This auto-registration would work for public users with no user-specific access grants. We will discuss a flow later in this post that describes how to create users with user-specific access grants.
    • A session is created for the user with an idle session timeout of 24 hours.
      • Note: The session expiration is not related to the ID token expiry. More on session expirations in the FAQ section below.
  4. Session ID is returned to the client.
  5. Client app initiates a replication by setting the session ID as the session cookie using the SessionAuthenticator as discussed in the docs.
  6. Sync Gateway checks the validity of the session to determine if the session has been deleted or has expired.
    • If the session is active, the session gets auto-extended to 24 hours if 10% of idle session timeout has elapsed.
  7. Following successful initialization, replication proceeds as usual, and document changes on the client app and Sync Gateway side are synchronized.
    • If the user is deleted during an active replication, the replication is terminated.
    • If the access grants associated with the user have changed, then documents that get impacted by the updated access grants won’t be replicated. For instance, if a user loses access to a channel then the documents in that channel won’t be pulled.

 

Associating Access Grants to Authenticated Users

 

Sync Gateway channels and roles are two key elements of Sync Gateway’s access control mechanism. They define the access grants associated with a user, dictating the set of documents that the user has read/write access to.

There are a couple of options to assign access grants to a user:

    • Dynamic assignment of users to channels or roles by the sync function with the access() or role() APIs using an access grant document. An access grant document specifies the channels or roles that a user must be assigned to.
    • Static assignment of grants to users via the admin _user REST API.

As you have seen from the previous OIDC authentication flows, Sync Gateway can be configured to automatically create the authenticated user in Sync Gateway following successful authentication. However, the user created is not associated with any access grants. This works for a public user with public channel access.

But what if you wanted to assign user specific access grants?

This task is typically handled via a backend application server that would be responsible for creating or updating the user. Sync Gateway is only responsible for OIDC authentication.

Here is a typical flow:

Associating access grants to authenticated users in Couchbase Sync Gateway

  1. A backend process or app server is responsible for registering users with the OIDC Provider.
  2. Subsequent to the registration, the app server creates corresponding user on Sync Gateway via the _user REST API or by adding a suitable access grant document.
  3. The next time the user logs into the app, OIDC authentication proceeds using the Implicit Flow procedures described earlier.
  4. Regardless of the type of OIDC flow, once the ID token is validated, Sync Gateway does not create a user because it already exists.
  5. Replication proceeds as usual using the authenticated user.
  6. If a user is updated on the OIDC Provider, the app server updates the corresponding user on the Sync Gateway via the _user REST API or by updating the access grant document.
    • If a user is deleted during an active replication, the replication is terminated.
    • If the access grants associated with the user have changed, then documents that get impacted by the updated access grants won’t be replicated. For instance, if a user loses access to a channel then the documents in that channel won’t be pulled.

 

Frequently Asked Questions (FAQ)

 

How is ID token expiration handled with replication?

Validation of ID token is done at authentication time when a replication is started. A token that expires during an active replication will not impact the ongoing replication. However, if the user associated with the replication is deleted, then the replication will be terminated. Similarly, if there are changes to access grants associated with the user, then that will immediately take effect in the ongoing replication.

Would session expiration terminate a continuous replication?

No. Session validation is done at authentication time when a replication is started. If a session expires during an active replication, that will not impact the ongoing replication. However, if the user associated with the replication is deleted, then the replication will be terminated. Similarly, if there are changes to access grants associated with the user, then that will immediately take effect in the ongoing replication.

Would deleting the sessions prior to their expiration terminate replication?

No. Session validation is done only at authentication time when a replication is started. So if a session expires during an active replication, that will not impact the ongoing replication. However, if the user associated with the replication is deleted, then the replication will be terminated. Similarly, if there are changes to access grants associated with the user, then that will immediately take effect in the ongoing replication.

Is it possible to use JWT claims for assigning channel grants?

That is not possible at this time.

What OIDC providers do you support?

We support any provider that is compliant with OIDC and JSON web token (JWT) standards.

More Resources

 

In this post, we described OpenID Connect (OIDC) authentication support in Couchbase Sync Gateway. In an upcoming post, we will discuss the Authorization Code Flow implementation with Sync Gateway.

Here are some additional resources:

 

If you have questions or feedback, please leave a comment below or email me at priya.rajagopal@couchbase.com. The Couchbase Forums are another good place to reach out with questions.

 

Catch up with the rest of the posts in this series on authentication and authorization:

 

Author

Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

Leave a reply