Skip to main content

The Customer Consent-Management Dashboard

Data Access includes a customer authorization dashboard which enables customers to manage the apps and intermediaries they have chosen to permission. This dashboard is designed to be embedded within your customer-facing web or mobile experience and is accessible at https://access.your-domain.com/embed/authorizations.

Access is authenticated with either:

  • An access token
  • (Deprecated) Nested JSON Web Tokens (JWTs), which are signed and encrypted

These options let you authenticate customers and display the dashboard without cookies.

Access Token​

Prerequisite

To get your credentials in the Data Provider Portal, go to Configuration > Consent Dashboard Management and select Generate API credentials.

  1. Request a one-time access token from the Request Token endpoint. Include client_id and client_secret in the request header. The request body must include the consent_management scope and the customerId (must match openid_connect_user_id).
    • Every token is single-use and expires in five minutes
    • Request a new token after use or expiration
  2. Set your iframe's src to the access_token you retrieved in the last step.

The widget is 512px wide and has a minimum height of 600px. If the iframe is wider, the widget centers; if taller, it can grow to the iframe height. The widget uses scrollbars if the content is longer than the height.

(Deprecated) JWTs​

warning

For new implementations, use an access token.

The following steps provide details on embedding the dashboard using JWTs.

A workflow that describes consent management

  1. Generate an encrypted admin JWT on your own systems using your shared secret and the customer's unique identifier.
  2. Use the admin JWT (step one) to request an encrypted, expiring, one-time use customer JWT from Data Access.
  3. Use the customer JWT (step two) as a query parameter to load the dashboard into an iframe.
info

Every customer JWT generated by Data Access is single-use and expires after 15 minutes.

Create an Admin JWT​

First, create an admin JWT using JSON Web Encryption (JWE). Use an appropriate encryption library to generate an admin JWT with your shared secret and the unique identifier for the customer. An example shared secret might be Jx2qSDdJy6BJfkjH7PPZ6OPnjbjd/qNI2vgbCRT30Qw=. MX strongly recommends using a Javascript Object Signing and Encryption (JOSE) library to handle JWE creation. There are many libraries and implementations available for different languages. Javascript and Ruby examples are shown here. Data Access uses AES256-GCM.

The encrypted object must contain the sub claim, for example {"sub": "sub-id-1234"}. This is the same as the subject identifier outlined in the OIDC spec. It's the unique identifier for that user in your system.

info

Keep your shared secret safe. When an admin request body is correctly decrypted in Data Access, it is considered to be from a trusted source.

Node.js
Ruby
Language:javascript

_19
const crypto = require('crypto');
_19
const { CompactEncrypt } = require('jose/jwe/compact/encrypt');
_19
const { compactDecrypt } = require('jose/jwe/compact/decrypt');
_19
class SecureMessageService {
_19
constructor(key) {
_19
this.encoder = new TextEncoder();
_19
this.decoder = new TextDecoder();
_19
this.key = crypto.createSecretKey(Buffer.from(key, 'base64'));
_19
}
_19
async encrypt(obj) {
_19
return await new CompactEncrypt(this.encoder.encode(JSON.stringify(obj)))
_19
.setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
_19
.encrypt(this.key);
_19
}
_19
async decrypt(encrypted) {
_19
const { plaintext } = await compactDecrypt(encrypted, this.key);
_19
return this.decoder.decode(plaintext);
_19
} }
_19
module.exports = SecureMessageService;

Create a Customer JWT​

Next, use this endpoint to create a JWT for the specified customer based on their unique subject identifier included in the previous section.

If a customer with the given sub hasn't yet been created in Data Access, using this endpoint will create it.

Endpoint: POST /admin/customers/jwt

Request
Response
Language:shell

_10
curl -L -X POST 'https://access.your-domain.com/admin/customers/jwt' \
_10
-H 'Content-Type: text/plain' \
_10
-d 'eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZ ... FEaFMXMQ4H9znE3yrJsMDy7WnCeJEg'

Embed the Dashboard​

To embed the customer consent-management widget in an iframe, pass the jwt query parameter into the route with the customer JWT as the value. This will authorize the view for the specified customer without reauthentication.

Endpoint: GET /embed/authorizations?jwt=${customer_jwt}

The widget is 512px wide and has a minimum height of 600px. If the iframe is wider, the widget centers; if taller, it can grow to the iframe height. The widget uses scrollbars if the content is longer than the height.

warning

Every JWT generated by Data Access is single-use. Once this token has been used to load the dashboard, a page refresh with the same token will result in a 404 Unauthorized status.

On this page