> For the complete documentation index, see [llms.txt](https://docs.iyzico.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iyzico.com/en/advanced/sso-integration.md).

# 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

{% hint style="info" %}
The SSO integration enables existing Merchant Panel users to authenticate through their organization's Identity Provider. User account creation and role management continue to be handled through the existing user management processes.
{% endhint %}

### General Flow

The SSO login process consists of the following steps:

1. The user enters their corporate email address on the Merchant Panel login page.
2. If the email domain matches one of the domains configured for SSO, the user is presented with the option to log in using SSO.
3. When the user selects the SSO login option, they are redirected to their organization's Identity Provider.
4. 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.
5. Upon successful authentication, the user is redirected back to the Merchant Panel.
6. iyzico verifies whether the user's account exists and is active.
7. 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.

{% hint style="warning" %}
**Important:** Successful authentication through the Identity Provider alone does not grant access to the Merchant Panel. The user must have an existing and active account in the iyzico Merchant Panel.
{% endhint %}

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

| Information                        | Description                                                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 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:

| Claim            | Description                               |
| ---------------- | ----------------------------------------- |
| `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 |

{% hint style="info" %}
The claims to be used and whether they are mandatory must be clarified during the integration process. If `merchantIdList` contains multiple values, it must be provided as an array.
{% endhint %}

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

| Information             | Description                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| 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:

* `openid`
* `profile`
* `email`

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.

{% hint style="warning" %}
The **exact** Redirect URI provided by iyzico for the relevant environment must be configured in the Identity Provider.
{% endhint %}

### User Login Scenarios

#### Login via SSO

1. The user enters their corporate email address on the Merchant Panel login page.
2. The system checks whether the email domain is configured for SSO.
3. The user selects the SSO login option.
4. The user is redirected to their corporate Identity Provider.
5. Upon successful authentication, the user is redirected back to the Merchant Panel.
6. 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.

| Scenario                             | Description                                                                                            | Displayed Message                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| 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."                          |
