Authorization Servers

Authorization servers are external OAuth 2.0 servers  that you can integrate with Paradym to add an additional layer of authentication during the credential issuance process. When an authorization server is configured, users must authenticate with that OAuth 2.0 server before they can receive their credentials. This allows you to gate credential issuance behind your own authentication system or a third-party identity provider.

Once a user successfully authenticates with the authorization server, their access token and ID token  (when available) are sent to an Attribute Provider when one is configured, which can use them to fetch and fulfill credential attributes. This enables you to retrieve user attributes from your existing identity and data systems seamlessly.

While it is possible to use an authorization server without an attribute provider, we do not recommend doing so. When using an authorization server, we always recommend deriving the attributes based on the authentication.

Configuring an Authorization Server

When configuring an authorization server, you need to provide the following information:

• The name of the authorization server, allowing you to recognize it easily.
• The URL of the authorization server, also known as the authorization server’s issuer identifier.
• The allowed redirect URIs of the trusted wallets you want to issue to.
  • These are the redirect URIs of the wallet application itself, not of the authorization server.
  • To be able to issue to the Paradym Wallet, use https://paradym.id/invitation/redirect.
  • We recommend using HTTPS redirect URLs for wallets instead of using deep links. Deep links can be registered by any application on iOS and Android, while Universal (iOS) and App (Android) links need to be verified by the wallet application.
• The authentication details, composed of the client identifier and the client secret.

Please note that the authorization server must either expose an OAuth Authorization Server Metadata  endpoint, or an OpenID Provider Configuration  endpoint. At the moment, we support both client_secret_basic and client_secret_post authentication methods, and the choice will automatically be made based on the authorization server metadata present at the endpoints.

Once you have these details, you can configure an authorization server using either the API or the Dashboard.

{
  "name": "Example Authorization Server",
  "url": "https://auth.example.com",
  "redirectUris": [
    "https://example.com/wallet-redirect"
  ],
  "authentication": {
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret"
  }
}

Configuring a Credential Template

Once you have configured an authorization server, you can link it to SD-JWT VC and mDoc credential templates. When linked, the authorization server is always used during the OpenID4VCI issuance flow for those credentials.

When linking an authorization server to a credential template, you can also configure:

• The scopes that will be included in the request to the authorization server.
• Any additional parameters to be included in the request to the authorization server.

Please note that all credential templates for a single issuance request must be configured to use the same authorization server.

{
  "name": "OpenID Profile",
  "description": "This is your OpenID profile.",
  "issuer": {
    "signer": "certificate",
    "keyType": "P-256"
  },
  "type": "org.example.OpenIdProfile",
  "validUntil": {
    "future": {
      "months": 6
    }
  },
  "attributes": {
    "org.example.OpenIdProfile": {
      "properties": {
        "name": {
          "type": "string",
          "name": "Name",
          "required": true
        },
        "given_name": {
          "type": "string",
          "name": "Given Name",
          "required": true
        },
        "family_name": {
          "type": "string",
          "name": "Family Name",
          "required": true
        }
      }
    }
  },
  "authorization": {
    "type": "oauth2",
    "authorizationServerId": "cml6cpayw00024b5jbqk5ecpw",
    "scopes": ["openid", "profile"],
    "additionalParameters": {
      "foo": "bar"
    }
  }
}