Target Audience: Developers, Administrators

OpenID Connect¶

Introduction¶

Payway supports OpenID Connect (OIDC), an identity layer built on top of the OAuth 2.0 protocol. OpenID Connect allows applications to verify the identity of users and obtain basic profile information in a secure and standardized way.

For configuration instructions on setting up OpenID in the Payway Administration Portal, see API Users - Implementing the OpenID Standard.

Well-Known Configuration Endpoint¶

Payway provides an OpenID Connect Discovery endpoint that returns metadata about the OpenID provider's configuration. This endpoint follows the OpenID Connect Discovery specification and allows clients to automatically discover endpoint URLs and supported features.

Request¶

No parameters are required. Simply make a GET request to the well-known configuration endpoint.

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/.well-known/openid-configuration
Production	https://payway-sso.azurewebsites.net/.well-known/openid-configuration

Authorization Endpoint¶

Initiates the authentication flow. Your application redirects the user to this endpoint to begin the login process.

Request¶

The following parameters must be supplied in the query string:

Parameter	Required	Description
response_type	Yes	Must be set to `code` for authorization code flow
client_id	Yes	The API user client ID from your Payway configuration
redirect_uri	Yes	The callback URL where the user will be redirected after authentication
scope	Yes	Space-separated list of scopes. Must include `openid`
code_challenge	No	Code challenge for PKCE (Proof Key for Code Exchange) flow. Recommended for public clients
code_challenge_method	No	Method used to generate the code challenge. Must be `S256` (SHA-256) if PKCE is used
state	No	A random value to maintain state between request and callback (prevents CSRF attacks). Recommended
nonce	No	A random value used to associate a client session with an ID token and to mitigate replay attacks. Recommended

Example request:

GET https://payway-sso.azurewebsites.net/openid/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid&
  state=random_state_value

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/openid/authorize
Production	https://payway-sso.azurewebsites.net/openid/authorize

Token Endpoint¶

Exchanges the authorization code for access tokens and refresh tokens.

Request¶

The HTTP-request must use the POST-method.

The following headers must be set:

Content-Type: application/x-www-form-urlencoded
Accept: application/json

The parameters must be supplied in the application/x-www-form-urlencoded format in the request body:

Parameter	Required	Description
grant_type	Yes	Must be `authorization_code` for initial token request or `refresh_token` for token refresh
code	Yes*	The authorization code received from the authorize endpoint (*required for authorization_code)
redirect_uri	Yes*	Must match the redirect_uri used in the authorization request (*required for authorization_code)
client_id	Yes	The API user client ID from your Payway configuration
client_secret	Yes	The API user client secret from your Payway configuration
code_verifier	No	Code verifier for PKCE (Proof Key for Code Exchange) flow. Required if code_challenge was used in the authorization request
refresh_token	Yes*	The refresh token (*required for refresh_token grant type)
scope	No	Space-separated list of scopes to request. Used with refresh_token grant type to potentially reduce scope

Example curl (Authorization Code):

curl --request POST \
  --url https://payway-sso.azurewebsites.net/openid/token \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&code=<received_authorization_code>&redirect_uri=https://yourapp.com/callback&client_id=<your_client_id>&client_secret=<your_client_secret>'

Example curl (Refresh Token):

curl --request POST \
  --url https://payway-sso.azurewebsites.net/openid/token \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token&refresh_token=<your_refresh_token>&client_id=<your_client_id>&client_secret=<your_client_secret>'

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/openid/token
Production	https://payway-sso.azurewebsites.net/openid/token

Successful Response¶

Example response from successful request:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "id_token": "eyJhbGciOiJIUzI1NiIs..."
}

ID Token Signing

ID tokens are signed using HS256 (HMAC with SHA-256) with your client_secret as the signing key. Payway does not provide a JWKS endpoint. You must validate tokens using the HS256 algorithm with your client secret directly.

ID Token Claims¶

The id_token is a JWT that contains claims about the authenticated user. After validating the token signature, you can decode it to access the following claims:

Claim	Always Included	Description
sub	Yes	Subject identifier - unique identifier for the user (account ID)
iss	Yes	Issuer - the Payway SSO service URL that issued the token
aud	Yes	Audience - your client_id that the token was issued for
iat	Yes	Issued at - Unix timestamp when the token was issued
exp	Yes	Expiration time - Unix timestamp when the token expires (1 hour from issuance)
at_hash	Yes	Access token hash - binds the ID token to the access token for security
nonce	Conditional	Included if a nonce parameter was provided in the authorization request (recommended)
email	Conditional	User's email address - included if `/openid/email` scope was requested
name	Conditional	User's full name - included if `/openid/profile` scope was requested

The claims included in the ID token depend on the scopes requested during the authorization request. Always include the openid scope to receive a valid ID token.

UserInfo Endpoint¶

Returns claims about the authenticated user. This endpoint requires a valid access token.

Request¶

The following headers must be set:

Authorization: Bearer <insert_access_token_here>

Example curl:

curl --request GET \
  --url https://payway-sso.azurewebsites.net/openid/userinfo \
  --header 'authorization: Bearer <insert_access_token_here>'

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/openid/userinfo
Production	https://payway-sso.azurewebsites.net/openid/userinfo

Successful Response¶

Example response from successful request:

{
  "sub": "account_id",
  "email": "user@example.com",
  "name": "John Doe"
}

End Session Endpoint¶

Terminates the user's session and optionally redirects them to a specified URL after logout. This endpoint implements the OpenID Connect RP-Initiated Logout specification.

Request¶

The following parameters can be supplied in the query string:

Parameter	Required	Description
id_token_hint	No	The ID token obtained during authentication. Used to identify which session to terminate
logout_hint	No	The account ID of the user to log out
client_id	No	The API user client ID from your Payway configuration
post_logout_redirect_uri	No	The URL to redirect the user to after logout. Must match a Post Logout Redirect URL configured in the API user settings
state	No	A value to maintain state between the logout request and callback. Returned to the client in the redirect URL

Example request:

GET https://payway-sso.azurewebsites.net/openid/endsession?
  id_token_hint=eyJhbGciOiJIUzI1NiIs...&
  client_id=your_client_id&
  post_logout_redirect_uri=https://yourapp.com/logged-out&
  state=random_state_value

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/openid/endsession
Production	https://payway-sso.azurewebsites.net/openid/endsession

Post-Logout Redirect Configuration

To use the post_logout_redirect_uri parameter, you must configure the allowed Post Logout Redirect URLs in your API user settings in PAP. See Implementing the OpenID Standard for configuration details.

Implementation Flow¶

The typical OpenID Connect authentication flow with Payway follows these steps:

Initiate Authentication
Your application redirects the user to Payway's authorization endpoint
User logs in using their Payway credentials
Receive Authorization Code
After successful authentication, Payway redirects the user back to your redirect_uri
The URL includes a code parameter containing the authorization code
Exchange Code for Tokens
Your application makes a server-side request to the token endpoint
Exchange the authorization code for access tokens and refresh tokens
Access User Information
Use the access token to call the userinfo endpoint
Retrieve user profile information
Token Refresh
When the access token expires, use the refresh token to obtain a new access token
Make a request to the token endpoint with grant_type=refresh_token

Error Handling¶

Payway handles errors differently depending on the context:

With Redirect URL Available (e.g., during authorization flow):

The user is redirected to the configured redirect URL with error information in query parameters:
error: The error code (e.g., invalid_request, access_denied, server_error)
state: The state value from the original request (if provided)

Example error redirect:

https://yourapp.com/callback?error=invalid_request&state=random_state_value

Without Redirect URL (e.g., token endpoint, userinfo endpoint):

A JSON response is returned with error details:
error: The error code
error_description: Human-readable description of the error

Example JSON error response:

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or expired"
}

State Validation

Always validate that the state parameter returned in callbacks matches the value you sent in the original request. This is critical for preventing CSRF attacks.