Products » Connect2id server » Documentation » Guides »

How to set up the Connect2id server with global DynamoDB tables, replication strategies

In November 2017 AWS announced global DynamoDB tables, enabling transparent asynchronous replication of table data between any number of AWS regions. A Connect2id server cluster can thus span two or more AWS regions, based on the same eventually consistent backend DynamoDB data.

Setup

  1. Configure your Connect2id server to persist data to DynamoDB.

  2. Launch a server instance in one of the desired AWS regions. The server will automatically create the DynamoDB tables and global secondary indices it needs for its operation.

  3. Open the DynamoDB console and for each created table enable streaming of new and old images. This is done via the table Overview tab, by clicking on Manage Stream.

    Streaming can also be activated via the AWS CLI and APIs.

    Connect2id server 7.6+ has a DynamoDB configuration setting allowing the tables to be created with enabled streaming by setting the dynamodb.enableStream Java system property to true. The console step can be skipped then.

  4. With streaming enabled, go to the Global Tables tab in the console. Choose Enable streams and leave View type at the default value (new and old images). Then specify all additional AWS regions where you want the table to be replicated. AWS with then automatically create the specified table replicas in those regions.

    The setup of a replication group can also be done via the AWS CLI and APIs.

  5. Launch the Connect2id server instances in the AWS regions with table replicas.

Replication strategies

To minimise your AWS replication bill you can configure replication for core Connect2id server data only and skip transient data, such as sessions.

You can also design your authorisation policy to issue self-contained tokens which don't use the database (as opposed to identifier-based tokens where the authorisation gets persisted):

  • Issue self-contained (JWT-encoded) access tokens. This is actually the default encoding of issued access tokens. Note that revocation doesn't have an immediate effect on those tokens (unless the token is for local access to the UserInfo endpoint of the Connect2id server). This can be mitigated by making their lifetime as short as possible.

  • If you need to issue refresh tokens make them also self-contained, by not persisting the end-user authorisation (with long_lived=false in the submitted consent object). This means that the capability to query the Connect2id server what particular access has been granted by an end-user to a client will be lost. Revoking client and end-user access will still work. Self-contained refresh tokens became available in Connect2id server 10.0.

Minimal replication

Here is a strategy which replicates core Connect2id server data only and skips short-lived / transient data, such as end-user sessions. Not replicating sessions means that if the user gets sent to authenticate or authorise in a different AWS region they will always be prompted to log in. Note that the OAuth 2.0 browser based flows (code, implicit and hybrid) should always be started and completed within the same region, otherwise clients may get unexpected authorisation code errors and other errors.

Tables to replicate:

  • clients -- The OAuth 2.0 client / OpenID relying party registrations.
  • federation_clients -- Index of OpenID Connect Federation 1.0 clients (if any).
  • revocation_journal -- Revoked clients and subjects (end-users).
  • id_access_tokens -- Identifier-based access tokens. If only self-contained (JWT-encoded) access tokens will be issued this table will not be used and hence it can be left with no replication.
  • long_lived_authorizations -- Long-lived (persisted) authorisations (consent) with any linked identifier-based refresh tokens. If authorisations will never be remembered and only self-contained refresh tokens will be issued this table will not be used and can be left with no replication.

Absolute minimal replication

Sending the user to authenticate or authorise in a different region will always require a new login. Clients will need to be re-authorised unless they were issued with self-contained refresh tokens. Revocation is not affected.

Tables to replicate:

  • clients -- The OAuth 2.0 client / OpenID relying party registrations.
  • federation_clients -- Index of OpenID Connect Federation 1.0 clients (if any).
  • revocation_journal -- Revoked clients and subjects (end-users).

Full replication

Enable replication for all DynamoDB tables. Clients can roam seamlessly between regions. OAuth 2.0 flows, such as the code flow, can be started and completed on a Connect2id server in a different region.