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
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 |