Auth service

Rafiki’s auth service provides you with a reference implementation of an Open Payments authorization server. You can use the auth service as an alternative to developing your own in-house service for grant authorization and authentication.

The authorization server:

• Authorizes incoming requests from clients (for example, third-party applications) to create payments and quotes on the backend
• Relays information about the interaction to the client and records the response
• Issues access tokens, which describe access rights, to clients and communicates with the resource server to validate those rights

Requirements

You must have the following when using the auth service.

• A Redis database for storing session data
• A Postgres database, separate from the backend service’s database, to store auth-related resources (grants, access tokens, and interactions)

  Note

  You can use the same Postgres database instance for both the backend and auth services, but separate database schemas are required within that instance to maintain a boundary between the objects those services manage.

• Integration with an identity provider

You must also set the environment variables for the auth service.

Incoming client auth requests

When a request comes from a client with an account known to your local instance of Rafiki, the auth service uses data stored in the auth service’s Postgres database.

When a request comes from a client registered with another instance of Rafiki, the auth service resolves the client’s key endpoint (for example, https://wallet.example.com/alice/jwks.json) to retrieve the client’s public keys, then filters out the correct key using the key id (kid) in the client’s signature.

Review the Open Payments documentation for more information about client keys.

Identity provider (IdP)

An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. When you use your Google account credentials to “Sign in with Google” on an app or website, for example, Google is acting as your identity provider.

You must integrate with an IdP when using Rafiki’s auth service because the Open Payments standard requires interactive outgoing payment grant requests. In an interactive request, there must be explicit interaction by an individual (for example, a client’s end-user) to approve or deny the grant. In this case, the grant must be explicitly approved before an outgoing payment is created.

Note

Rafiki’s frontend service requires an IdP for authentication and user management of your Rafiki Admin users. Out of the box, Rafiki uses Ory Kratos, a cloud-based user management system. Kratos is for internal use only and cannot be used as your customer-facing Open Payments authorization server.

For more information about interactive grants and how they work with identity providers, review the Identity Provider page and the Grant negotiation and authorization page in the Open Payments docs.

GraphQL Auth Admin API

The auth service exposes a GraphQL Auth Admin API to manage auth-related resources, such as Open Payments grants.

Environment variables

Required

Variable	Helm value name	Default	Description
AUTH_DATABASE_URL	auth.postgresql.host, auth.postgresql.port, auth.postgresql.username, auth.postgresql.database, auth.postgresql.password	postgresql://postgres:password@localhost:5432/auth_development	The URL of the Postgres database storing your Open Payments grant data. For Helm, these components are provided individually.
AUTH_SERVER_URL	auth.server.domain	undefined	The public endpoint for your Rafiki instance’s public Open Payments routes.
COOKIE_KEY	auth.cookieKey	undefined	The koa KeyGrip key that is used to sign cookies for an interaction session.
IDENTITY_SERVER_URL	auth.identityServer.domain	undefined	The URL of your IdP’s server, used by the authorization server to inform an Open Payments client of where to redirect the end-user to start interactions.
IDENTITY_SERVER_SECRET	auth.identityServer.secret	undefined	A shared secret between the authorization server and the IdP server; the authorization server will use the secret to secure its IdP-related endpoints. When the IdP server sends requests to the authorization server, the IdP server must provide the secret via an x-idp-secret header.
REDIS_URL	auth.redis.host, auth.redis.port	redis://127.0.0.1:6379	The connection URL for Redis. For Helm, these components are provided individually.

Conditionally required

Variable	Helm value name	Default	Description
TRUST_PROXY	auth.trustProxy	false	Must be set to true when running Rafiki behind a proxy. When true, the X-Forwarded-Proto header is used to determine if connections are secure.

Optional

Variable	Helm value name	Default	Description
ACCESS_TOKEN_DELETION_DAYS	auth.accessToken.deletionDays	30	The days until expired and/or revoked access tokens are deleted.
ACCESS_TOKEN_EXPIRY_SECONDS	auth.accessToken.expirySeconds	600 (10 minutes)	The expiry time, in seconds, for access tokens.
ADMIN_API_SIGNATURE_VERSION	auth.adminApi.signatureVersion	1	The version of the request signing algorithm used to generate signatures.
ADMIN_API_SIGNATURE_TTL_SECONDS	auth.adminAPI.signatureTtlSeconds	30	The TTL, in seconds, for which a request’s signature will be valid.
ADMIN_PORT	auth.port.admin	3003	The port of your Rafiki Auth Admin API server.
AUTH_PORT	auth.port.auth	3006	The port of your Open Payments authorization server.
DATABASE_CLEANUP_WORKERS	auth.workers.cleanup	1	The number of workers processing expired or revoked access tokens.
ENABLE_MANUAL_MIGRATIONS	auth.enableManualMigrations	false	When true, you must run the auth Postgres database manually with the command npm run knex – migrate:latest –envproduction
INCOMING_PAYMENT_INTERACTION	auth.interaction.incomingPayment	false	When true, incoming Open Payments grant requests are interactive
INTERACTION_EXPIRY_SECONDS	auth.interactionExpirySeconds	600 (10 minutes)	The time, in seconds, for which a user can interact with a grant request before the request expires.
INTERACTION_PORT	auth.port.interaction	3009	The port number of your Open Payments interaction-related APIs.
INTROSPECTION_PORT	auth.port.introspection	3007	The port of your Open Payments access token introspection server.
LIST_ALL_ACCESS_INTERACTION	auth.interaction.listAll	true	When true, grant requests that include a list-all action will require interaction. In these requests, the client asks to list resources that it did not create.
LOG_LEVEL	auth.logLevel	info	Pino log level
NODE_ENV	auth.nodeEnv	development	The type of node environment: development, test, or production.
QUOTE_INTERACTION	auth.interaction.quote	false	When true, quote grants are interactive.
REDIS_TLS_CA_FILE_PATH	auth.redis.tlsCaFile	''	Redis TLS config
REDIS_TLS_CERT_FILE_PATH	auth.redis.tlsCertFile	''	Redis TLS config
REDIS_TLS_KEY_FILE_PATH	auth.redis.tlsKeyFile	''	Redis TLS config
WAIT_SECONDS	auth.grant.waitSeconds	5	The wait time, in seconds, included in a grant request response (grant.continue).

Token introspection

When a client makes a request to a resource server, the resource server communicates with the authorization server to:

• Check the validity of the client’s access token
• Determine whether the client is authorized to access protected resources

This process is called token introspection.

The token-introspection package is a client library for making GNAP token introspection requests to an authorization server. It describes how the Rafiki backend and auth services communicate to validate access tokens. If you’re using Rafiki’s auth service, there’s nothing you need to do with this package. Rafiki automatically runs the package internally. If you’re writing your own auth service, you may find the files within the package to be helpful.