End to End Identity

CipherStash Proxy can propagate individual customer identity and context with data access logs for visibility.

Overview

Identity and Context are passed using custom SET commands that behave similarly to other PostgreSQL SET commands. Adding these commands to your application unlocks powerful new capabilities.

Identity enables a JWT to be passed to the proxy, verified and the sub (subject) and aud (audience) values to be extracted (if present) and passed with audit logs. See RFC: 7519 JSON Web Token for further details.

Context accepts arbitrary JSON data to be associated with the data access logs. The context data can be used to refine search and analysis in the dashboard.

Available commands:

• SET IDENTITY { TO | = } 'jwt_token'
• SET CONTEXT { TO | = } 'json'
• RESET {IDENTITY | CONTEXT}

Both Identity and Context data are tied to the current connection or transaction context. The application is responsible for ensuring that data is reset.

<a name="configure-provider"></a> Configuring an Identity Provider

Configure Issuer and Audience for JWT verification using the Cipherstash CLI.

The following assumes you have the CLI configured.

Add an authorised issuer and audience to your account:

1stash identify provider trust --issuer auth.domain.com --audience api.domain.com
2

The issuer should be the domain that hosts the JSON Web Key issued by the Authorisation Server:

1https://{issuer}/.well-known/jwks.json
2

The audience should be the audience value in your JWT.

Multiple values can be provided for both issuer and audience as comma-delimited strings

1stash identify provider trust --issuer "auth.domain.com, auth.domain.org"  --audience "api.domain.com, api.domain.org"
2

Revoke issuer and audience individually or together:

1stash identify provider revoke --issuer
2stash identify provider revoke --audience
3stash identify provider revoke --issuer --audience
4

See the Cipherstash CLI Reference for more details.

<a name="set-identity"></a> Set Identity

SQL Command to set a JWT token that will be verified and decoded.

Syntax

1SET IDENTITY { TO | = } 'jwt_token'
2

Description

The SET IDENTITY command changes the run-time identity.

The input parameter is expected to be a valid JWT token.

The token is validated against authorised issuers and audiences configured in the CipherStash Workspace.

If issuer and audience are valid, the JWT token is decoded and the issuer, audience and subscriber values are extracted and propagated with the Statement Audit Log.

Issuers and Audience

In order to validate and decode JWT tokens, the approved Issuers and Audiences (if appropriate) need to be added to your CipherStash Workspace configuration.

{INSERT DETAILS ON ISSUERS}

Example

1
2## Set JWT Token
3SET IDENTITY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJzdWJzY3JpYmVyIiwic3ViIjoiMTIzNDU2Nzg5MCIsInVzZXJuYW1lIjoiVXNlcjQyIiwiaWF0IjoxNTE2MjM5MDIyfQ.o1SrsJO_CLwdcPGHrgacQrP8wwIQr-CgoO99-pOVfvQ'
4
5## Decoded Data
6{
7  "aud": "",
8  "sub": "1234567890",
9  "username": "User42",
10  "iat": 1516239022
11}
12
13## Propagated Data
14
15{
16  "aud": "",
17  "sub": "1234567890"
18}
19

Reset Identity

Immediately clear identity information.

Syntax

1RESET IDENTITY
2

Description

The RESET IDENTITY command clears the run-time identity data.

<a name="set-context"></a> Set Context

Sets arbitrary JSON data to be with statement Audit log.

Syntax

1SET CONTEXT { TO | = } 'json'
2

Description

The SET CONTEXT command changes the run-time context that is propagated with the Statement Audit Log.

The input parameter is expected to be a valid JSON string. The parameter will be checked to ensure it can be parsed as JSON, but no other restrictions or requirements apply.

If the input parameter is invalid, a parse error is returned.

Reset Context

Immediately clear context information.

Syntax

1RESET CONTEXT
2

Description

The RESET CONTEXT command clears the run-time context.

Rails Example

In Rails, an around_action can SET and RESET the context or identity for all statements run inside the controller. Context data can be loaded or extracted from the session.

1class BaseController < ApplicationController
2  around_action :wrap_in_context
3
4  private
5    def wrap_in_context
6      begin
7        ActiveRecord::Base.connection.execute("SET CONTEXT '{...}'")
8        yield
9      ensure
10        ActiveRecord::Base.connection.execute("RESET CONTEXT")
11      end
12    end
13end
14
15

Lifecycle

Transaction Mode

In transaction mode, a client is connected for the duration of a transaction. The connection is returned to the pool once the transaction is complete.

This mode is enabled by default.

An application can start a transaction and execute multiple statements against the same underlying connection to the database.

As transactions complete, and connections returned to the pool, any set identity or context information is discarded.

Data can be changed at any time by executing SET {IDENTITY | CONTEXT} or RESET {IDENTITY | CONTEXT}.

Session Mode

Session mode is the normal behaviour of Postgres connections in the wild. In Session mode, the connection context lives until the client closes the connection.

The identity is retained until the next SET {IDENTITY | CONTEXT} statement or RESET {IDENTITY | CONTEXT} is called.

Example Session Mode Flow

In this example, the App has called SET IDENTITY before executing multiple statements.

Both statements will be executed by the proxy with the same identity.

1App   -> Connect
2
3Proxy -> Database Connection
4
5App   -> SET IDENTITY
6
7App   -> Statement
8
9Proxy -> Executes Statement [with IDENTITY]
10
11App   -> Statement
12
13Proxy -> Executes Statement [with IDENTITY]
14
15App   -> Close Connection
16