Skip to content
GitHub

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)
  • 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.

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

VariableHelm Value NameDefaultDescription
ACCESS_TOKEN_DELETION_DAYSauth.accessToken.deletionDays30days until expired or revoked access tokens are deleted
ACCESS_TOKEN_EXPIRY_SECONDSauth.accessToken.expirySeconds10 * 60expiry time in seconds for access tokens (default: 10 minutes)
ADMIN_PORTauth.port.admin3003Admin API GraphQL Server port
AUTH_DATABASE_URLauth.postgresql.host, auth.postgresql.port, auth.postgresql.username, auth.postgresql.database, auth.postgresql.passwordpostgresql://postgres:password@localhost:5432/auth_developmentPostgres database URL of database storing the grant data; For Helm, these components are provided individually.
AUTH_PORTauth.port.auth3006port of this Open Payments Auth Server
AUTH_SERVER_URLPublic endpoint for this Rafiki instance’s public Open Payment routes.
COOKIE_KEYauth.cookieKeykoa KeyGrip key that is used to sign cookies for an interaction session
DATABASE_CLEANUP_WORKERSauth.workers.cleanup1number of workers processing expired or revoked access tokens
IDENTITY_SERVER_URLauth.identityServer.domainendpoint of the identity server controlled by the Account Servicing Entity
IDENTITY_SERVER_SECRETauth.identityServer.secretAPI key to fetch the identity server endpoint
INCOMING_PAYMENT_INTERACTIONauth.interaction.incomingPaymentfalseflag - incoming payments grant requests are interactive or not
INTERACTION_EXPIRY_SECONDSauth.interactionExpirySeconds600time in seconds for which a user can interact with a grant request
INTERACTION_PORTauth.port.interaction3009Port number for the interaction APIs
INTROSPECTION_PORTauth.port.introspection3007port of this Open Payments Auth - Token Introspection Server
LIST_ALL_ACCESS_INTERACTIONtrueSpecify 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_LEVELauth.logLevelinfoPino Log Level
NODE_ENVauth.nodeEnvdevelopmentnode environment, development, test, or production
QUOTE_INTERACTIONauth.interaction.quotefalseflag - quote grants are interactive or not
REDIS_TLS_CA_FILE_PATHauth.redis.tlsCaFile''Redis TLS config
REDIS_TLS_CERT_FILE_PATHauth.redis.tlsCertFile''Redis TLS config
REDIS_TLS_KEY_FILE_PATHauth.redis.tlsKeyFile''Redis TLS config
REDIS_URLauth.redis.host, auth.redis.portredis://127.0.0.1:6379The connection URL for Redis. For Helm, these components are provided individually.
TRUST_PROXYfalseflag to use X-Forwarded-Proto header to determine if connections is secure
WAIT_SECONDSauth.grant.waitSeconds5wait time included in grant request response (grant.continue)
ENABLE_MANUAL_MIGRATIONSauth.enableManualMigrationsfalseWhen set to true, user needs to run database manually with command npm run knex -- migrate:latest --env production