Authorization services

Authorization services describe OAuth providers that can be used with the OID4VCI issuance flow in Document Rails.

When configuring the authorization service, make sure it supports the following specifications:

Supported authentication methods

Only client_secret_post authentication method is supported at the moment.

Operation modes

Document Rails supports two modes of operation for authorization services.

Regular mode

In regular mode, holder's wallet communicates with your authorization server directly, acquiring the access token and passing it to Document Rails for introspection.

sequenceDiagram
    participant Wallet
    participant Authorization server
    participant Document Rails

    Wallet->>Authorization server: Authorize endpoint invocation
    Authorization server->>Wallet: Authorization URL
    Note over Wallet: User authenticates in their browser

    Wallet->>Authorization server: Authorization code
    Authorization server->>Wallet: Access token

    Wallet->>Document Rails: Access token

When utilizing regular mode, make sure your authorization server is ready to handle practically arbitrary client_id values wallets may provide. If your authorization server expects a limited and well-known list of clients, we recommend utilizing proxy mode instead.

Usually, this mode requires implementation of the following specifications in addition to the ones listed above:

Proxy mode

In proxy mode, holder's wallet communicates with Document Rails for authorization, allowing your authorization server to configure just one known client for credential offers you expect to handle.

sequenceDiagram
    participant Wallet
    participant Document Rails
    participant Authorization server

    Wallet->>Document Rails: Authorize endpoint invocation
    Document Rails->>Authorization server: Authorize endpoint invocation
    Authorization server->>Document Rails: Authorization URL
    Document Rails->>Wallet: Authorization URL
    Note over Wallet: User authenticates in their browser

    Authorization server->>Document Rails: Authorization code
    Document Rails->>Authorization server: Authorization code
    Authorization server->>Document Rails: Access token
    Note over Document Rails: Proxied authorization code is generated

    Document Rails->>Wallet: Proxied authorization code
    Wallet->>Document Rails: Proxied authorization code

    Note over Document Rails: Proxied access token is generated
    Document Rails->>Wallet: Proxied access token

Since in this mode your authorization server doesn't communicate with the wallet directly, it is possible to configure just one client_id for Document Rails, limiting the exposure scope and deployment time.

Examples

Create regular authorization service (JavaScript)Create proxied authorization service (JavaScript)List authorization services (JavaScript)Delete authorization service (JavaScript)Restore authorization service (JavaScript)

import { createAuthService } from "@vaultie/document-rails";

const response = await createAuthService(
    client,
    accessToken,
    organizationId,
    {
        // OAuth client identifier.
        client_id: "impressum",

        // OAuth client secret.
        client_secret: "qwertyuiop",

        // URL of the OAuth authorization server.
        authorization_server_url: "https://authelia.local",
    },
);

import { createAuthService } from "@vaultie/document-rails";

const response = await createAuthService(
    client,
    accessToken,
    organizationId,
    {
        // OAuth client identifier.
        client_id: "impressum",

        // OAuth client secret.
        client_secret: "qwertyuiop",

        // URL of the OAuth authorization server.
        authorization_server_url: "https://authelia.local",

        // Proxy configuration.
        proxy: {
            // List of scopes to request from your authorization server
            // during the `authorization_endpoint` invocation.
            scopes: ["openid", "profile", "email"]
        }
    },
);

import { listAuthServices } from "@vaultie/document-rails";

const response = await listAuthServices(
    client,
    accessToken,
    organizationId
);

import { deleteAuthService } from "@vaultie/document-rails";

await deleteAuthService(
    client,
    accessToken,
    organizationId,
    authServiceId
);

import { restoreAuthService } from "@vaultie/document-rails";

await restoreAuthService(
    client,
    accessToken,
    organizationId,
    authServiceId
);