SSO Integration
Merchant Panel SSO Integration
Purpose
The iyzico Merchant Panel supports Single Sign-On (SSO) through corporate Identity Providers (IdPs). This integration enables merchant users to securely and conveniently access the iyzico Merchant Panel using their organization's existing authentication infrastructure.
SSO integration allows organizations to leverage their existing authentication and security policies. Users' existing accounts and permissions in the iyzico Merchant Panel remain unchanged.
Scope
The SSO integration provides the following capabilities:
Authentication through corporate Identity Providers that support OpenID Connect (OIDC)
An SSO login option based on the user's corporate email domain
Verification of the user's Merchant Panel account following successful authentication through the Identity Provider
SSO access exclusively for users who have an existing and active account in the Merchant Panel
Preservation of users' existing roles and permissions
Appropriate informational messages for unsuccessful login attempts
General Flow
The SSO login process consists of the following steps:
The user enters their corporate email address on the Merchant Panel login page.
If the email domain matches one of the domains configured for SSO, the user is presented with the option to log in using SSO.
When the user selects the SSO login option, they are redirected to their organization's Identity Provider.
The user completes authentication through the Identity Provider. Additional authentication steps, such as Multi-Factor Authentication (MFA), may be required depending on the organization's security policies.
Upon successful authentication, the user is redirected back to the Merchant Panel.
iyzico verifies whether the user's account exists and is active.
If the account exists and is active, a Merchant Panel session is established. If the account does not exist or is inactive, the login process is rejected and the user is informed accordingly.
Identity and Access Management
User Mapping
During the first SSO login, the user is matched to their existing Merchant Panel account using their email address. The email address is normalized before matching. Following the initial mapping, the user's identity is verified through the Identity Provider identifier during subsequent logins.
The following conditions must be met for SSO login:
The user must have an existing account in the iyzico Merchant Panel
The user's account must be active
Authentication through the Identity Provider must be completed successfully
Roles and Permissions
Logging in through SSO does not change the user's existing roles or permissions. Roles and permissions continue to be managed through the existing user management processes. The Master User can update user roles within the scope of their existing administrative permissions.
Merchant Prerequisites
Identity Provider Configuration
The merchant must create an OIDC-enabled application within their corporate Identity Provider. Identity Providers such as Okta and Amazon that support OIDC can be used with the appropriate configuration.
Required Information
The following information and configurations must be provided during the integration process:
OIDC Issuer URL
The issuer URL of the Identity Provider. Example: https://{your-domain}.okta.com/oauth2/default
Authorization Server Information
Information related to the authorization server used by the Identity Provider.
Client ID
The client identifier associated with the OIDC application.
Client Secret
The client secret associated with the OIDC application. It must be securely shared in accordance with the integration configuration.
Test Users
Test accounts that can be used to validate successful and unsuccessful login scenarios.
MFA and Security Policies
Additional authentication requirements and relevant security policies to be applied during authentication.
User Assignments and Access Groups
Definition of the users and groups authorized to access the SSO application.
Claim Mapping
Configuration of the user information to be provided by the Identity Provider.
Claim Requirements
Claims containing user information are used during OIDC authentication. The primary requirement is that the user's email address must be provided through the email claim.
Depending on the integration requirements and configuration, the following claims may also be used:
email
The user's email address
given_name
The user's first name
family_name
The user's last name
gsmNumber
The user's phone number
merchantIdList
The merchant IDs associated with the user
Security and Secret Management
The Client Secret and other authentication credentials must be stored securely. An appropriate process for key rotation and credential updates must be established between the parties.
Information Provided by iyzico
iyzico provides the following information required to configure the SSO integration:
Sign-in Redirect URI
The URL to which the Identity Provider redirects the user following successful authentication.
Environment Information
Integration details for the staging and production environments.
OIDC Scope Requirements
The required base scope values.
Claim Requirements
The user information expected during authentication.
Redirect URI and Scope Information
The base scope values used for OIDC integration are:
openidprofileemail
The Redirect URI values are provided by iyzico during the integration process and must be registered in the relevant application configuration on the Identity Provider side. Separate URIs may be defined for the staging and production environments.
User Login Scenarios
Login via SSO
The user enters their corporate email address on the Merchant Panel login page.
The system checks whether the email domain is configured for SSO.
The user selects the SSO login option.
The user is redirected to their corporate Identity Provider.
Upon successful authentication, the user is redirected back to the Merchant Panel.
If the user's account exists and is active, access to the panel is granted.
If the user already has an active session with the Identity Provider, they may not need to enter their password again, depending on the organization's policies.
Email Address Not Configured for SSO
If the email domain is not configured for SSO, the user can continue through the standard login process using the existing authentication method.
Error Scenarios and User Messages
In the following cases, the login process is not completed and the corresponding message is displayed to the user. In the event of an authentication or service error, the user is redirected back to the login page.
User account not found
Even though authentication was successful, no Merchant Panel account matches the user's email address.
"No account is registered with this email address. Please contact your administrator."
User account inactive
The Merchant Panel account exists but is inactive.
"This account is inactive. Please contact your administrator."
General authentication error
Cases such as an invalid or expired token or a validation mismatch.
"An issue occurred during login. Please try again."
Identity Provider connectivity issue
An Identity Provider-related error or connectivity problem.
"SSO login is currently unavailable. Please try again later."
Last updated
