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 is responsible for:

• Authorizing incoming requests from clients (e.g., third-party applications) to create payments and quotes on the backend
• Relaying information about the interaction to the client and recording the response
• Issuing access tokens to clients and communicating with the resource server to validate each client’s access rights

Requirements

The following are required 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 (e.g., 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.

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.

Integration with an IdP is required when using Rafiki’s auth service because Open Payments requires interactive outgoing payment grant requests. This means there must be explicit interaction by an individual (typically a client’s end user/your customer) to approve or deny an outgoing payment before a grant is issued.

Note

Rafiki’s frontend service requires an IdP for authentication and user management of your administrators. Out of the box, Rafiki uses Ory Kratos to enable your admins to access the Admin API. Kratos is for internal use and cannot be used for your customer-facing Open Payments authorization server.

For more information about interactive grants and how they work with identity providers, review 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

Variable	Helm Value Name	Default	Description
ACCESS_TOKEN_DELETION_DAYS	auth.accessToken.deletionDays	30	days until expired or revoked access tokens are deleted
ACCESS_TOKEN_EXPIRY_SECONDS	auth.accessToken.expirySeconds	10 * 60	expiry time in seconds for access tokens (default: 10 minutes)
ADMIN_PORT	auth.port.admin	3003	Admin API GraphQL Server port
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	Postgres database URL of database storing the grant data; For Helm, these components are provided individually.
AUTH_PORT	auth.port.auth	3006	port of this Open Payments Auth Server
AUTH_SERVER_URL			Public endpoint for this Rafiki instance’s public Open Payment routes.
COOKIE_KEY	auth.cookieKey		koa KeyGrip key that is used to sign cookies for an interaction session
DATABASE_CLEANUP_WORKERS	auth.workers.cleanup	1	number of workers processing expired or revoked access tokens
IDENTITY_SERVER_URL	auth.identityServer.domain		endpoint of the identity server controlled by the Account Servicing Entity
IDENTITY_SERVER_SECRET	auth.identityServer.secret		API key to fetch the identity server endpoint
INCOMING_PAYMENT_INTERACTION	auth.interaction.incomingPayment	false	flag - incoming payments grant requests are interactive or not
INTERACTION_EXPIRY_SECONDS	auth.interactionExpirySeconds	600	time in seconds for which a user can interact with a grant request
INTERACTION_PORT	auth.port.interaction	3009	Port number for the interaction APIs
INTROSPECTION_PORT	auth.port.introspection	3007	port of this Open Payments Auth - Token Introspection Server
LIST_ALL_ACCESS_INTERACTION		true	Specify whether grant requests including a list-all action should require interaction. In these requests, the client asks to list resources that they themselves did not create.
LOG_LEVEL	auth.logLevel	info	Pino Log Level
NODE_ENV	auth.nodeEnv	development	node environment, development, test, or production
QUOTE_INTERACTION	auth.interaction.quote	false	flag - quote grants are interactive or not
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
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.
TRUST_PROXY		false	flag to use X-Forwarded-Proto header to determine if connections is secure
WAIT_SECONDS	auth.grant.waitSeconds	5	wait time included in grant request response (grant.continue)
ENABLE_MANUAL_MIGRATIONS	auth.enableManualMigrations	false	When set to true, user needs to run database manually with command npm run knex -- migrate:latest --env production