---
title: "SSO authentication"
sidebar_label: "SSO authentication"
sidebar_position: 4
description: "How to authenticate in the Control panel via SSO and what errors may occur"
---

import Formbricks from '@theme/MDXComponents/Formbricks'
import {CustomTable} from '@selectel/docux/components'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import {TabItemLabel} from '@selectel/docux/components'

# SSO authentication

## First authentication \{#first-auth}

If a user was [added manually](/access-control/manage/add-user.mdx#add-panel-user), after being invited to the account, they will receive an email with a link for SSO authorization and the federation ID.

If automatic user creation was enabled when creating the federation on the Selectel side, the link for first authentication is provided by the [Account Owner](/access-control/user-types.mdx#account-owner) or a user with the [`iam_admin`](/access-control/role-reference.mdx#iam-admin) role.

<Tabs queryString="first-auth">
  <TabItem value="email-link" default>
    <TabItemLabel>
      Login via link from email
    </TabItemLabel>

    1. In the email, click **Log in via SSO**.
    2. Enter the federation ID.
    3. Optional: to avoid entering the federation ID every time you log in, select the **Save federation** checkbox.
    4. Click **Log in via SSO**. You will be redirected to the authorization page at the identity provider.
    5. Authorize with the identity provider. After authorization, you will be redirected to the login page in the Control panel.
    6. If your full name is not specified, enter it.
    7. Click **Log in via SSO**.
  </TabItem>

  <TabItem value="direct-link">
    <TabItemLabel>
      Login via direct link
    </TabItemLabel>

    1. Follow the link provided by the [Account Owner](/access-control/user-types.mdx#account-owner) or a user with the [`iam_admin`](/access-control/role-reference.mdx#iam-admin) role.
    2. If your full name is not specified, enter it.
    3. Click **Log in via SSO**.
    4. If your email is not specified, enter it.
    5. If your full name is not specified, enter it.
    6. Click **Log in via SSO**.
  </TabItem>
</Tabs>

## Authentication at each login \{#auth}

1. In the [Control panel](https://my.selectel.ru/login/) on the login page, click **Log in via SSO**.
2. Enter the federation ID or select a saved federation. You can find the federation ID in the invitation email or request it from the [Account Owner](/access-control/user-types.mdx#account-owner) or a user with the [`iam.admin`](/access-control/role-reference.mdx#iam-admin) role.
3. Optional: to avoid entering the new federation ID every time you log in, select the **Save federation** checkbox.
4. Click **Log in via SSO**. You will be redirected to the authorization page at the identity provider.
5. Authorize with the identity provider.

## Authentication errors \{#errors}

### Via SAML protocol \{#saml-errors}

If SAML federation was configured incorrectly, errors may occur during federated user authentication. Error groups:

* SAML001 — SAML099 – federation configuration errors on the Selectel side;
* SAML100 — SAML199 – validation errors on the identity provider side (SAML Response);
* SAML200 — SAML299 – other errors.

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Error</th><th>Cause</th><th>Solution</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <th colspan="3">SAML001 – SAML099 — configuration errors on the Selectel side</th>
      </tr>

      <tr>
        <th>SAML001: saml\_idp\_is\_not\_configured</th><td>SAML-compatible provider was not added on the Selectel side</td><td>Check the federation settings on the Selectel side</td>
      </tr>

      <tr>
        <th>SAML002: saml\_idp\_certs\_not\_configured</th><td>The federation in Selectel is missing a certificate</td><td>For the federation, [add a certificate](/access-control/federations/manage-saml/certificates.mdx#add-certificate) issued by the identity provider</td>
      </tr>

      <tr>
        <th colspan="3">SAML100 – SAML199 — SAML Response validation errors</th>
      </tr>

      <tr>
        <th>SAML100: saml\_response\_invalid\_request\_id</th>

        <td>
          Incorrect SAML request identifier. Possible causes:

          * repeated authentication attempt within a single request (SAML Response);
          * the authentication time limit has expired — after navigating to the authentication page, the user entered credentials 10 or more minutes later
        </td>

        <td>Navigate to the authentication page from the Selectel Control panel again and authorize</td>
      </tr>

      <tr>
        <th>SAML101: saml\_response\_invalid\_destination</th><td>The **Destination** parameter in the SAML Response is set incorrectly</td>

        <td>
          Set the correct URL for the SAML Assertion Consumer Service on the identity provider side:

          * in Keycloak — **Valid Redirect URIs** field, more details in the [Create a SAML federation for Keycloak](/access-control/federations/manage-saml/create-saml-federation-keycloak.mdx) guide;
          * in AD FS — **Relying party SAML 2.0 SSO service URL** field, more details in the [Create a SAML federation for AD FS 2.0](/access-control/federations/manage-saml/create-saml-federation-adfs.mdx) guide
        </td>
      </tr>

      <tr>
        <th>SAML102: saml\_response\_invalid\_in\_response\_to</th><td>The SAML Response was created for an authentication request with a different identifier</td><td>Navigate to the authentication page from the Selectel Control panel again and authorize</td>
      </tr>

      <tr>
        <th>SAML103: saml\_response\_invalid\_issuer</th><td>An incorrect value was specified for the **IdP Issuer** field when creating the federation on the Selectel side</td><td>In the federation settings in Selectel, set the correct value in the **IdP Issuer** field</td>
      </tr>

      <tr>
        <th>SAML104: saml\_response\_invalid\_signature</th>

        <td>
          The signature of the received SAML Response is set incorrectly. Possible causes:

          * the identity provider returned an incorrect SAML Response. You can check the correctness of the SAML Response using third-party utilities (for example, [Onelogin](https://www.samltool.com/decode.php));
          * an incorrect certificate is added for the federation in Selectel
        </td>

        <td>
          * for an incorrect SAML Response: check the federation settings on the identity provider side;
          * for an incorrect certificate: [add the correct certificate](/access-control/federations/manage-saml/certificates.mdx#identity-provider-certificates)
        </td>
      </tr>

      <tr>
        <th>SAML105: saml\_response\_subject\_not\_found</th><td>The **Subject** section is missing from the received SAML Response</td><td>Configure the federation on the identity provider side so that the **Subject** section is included in the SAML Response</td>
      </tr>

      <tr>
        <th>SAML106: saml\_response\_name\_id\_not\_found</th><td>The **NameID** parameter is missing from the received SAML Response</td>

        <td>
          Configure the federation on the identity provider side so that the **NameID** parameter is included in the SAML Response:

          * in AD FS — [configure Claims Mapping](/access-control/federations/manage-saml/create-saml-federation-adfs.mdx#configure-claims-mapping);
          * Keycloak – no configuration required. Please re-authenticate later
        </td>
      </tr>

      <tr>
        <th>SAML107: saml\_response\_user\_not\_found</th><td>User does not exist in Selectel</td><td>[Add a panel user](/access-control/manage/add-user.mdx#add-panel-user) with the login method **Federation**.<br /> If the user is already added, ensure that the value of the `ExternalID` field for the created user matches the user identifier on the identity provider side</td>
      </tr>

      <tr>
        <th>SAML108: saml\_response\_invalid\_assertion\_xml</th>

        <td>
          Incorrect SAML Response format. You can check the SAML Response using third-party utilities (for example, [Onelogin](https://www.samltool.com/decode.php))
        </td>

        <td>
          * re-authentication;
          * check the federation settings on the identity provider side
        </td>
      </tr>

      <tr>
        <th>SAML109: saml\_response\_invalid\_assertion</th><td>Incorrect SAML Response</td>

        <td>
          Check the federation settings on the identity provider side. You can check the SAML Response using third-party utilities (for example, [Onelogin](https://www.samltool.com/decode.php))
        </td>
      </tr>

      <tr>
        <th colspan="3">SAML200 – SAML299 — other errors</th>
      </tr>

      <tr>
        <th>SAML200: saml\_internal\_error</th><td>Requires clarification</td><td>[Create a ticket](https://my.selectel.ru/tickets)</td>
      </tr>

      <tr>
        <th>SAML201: saml\_malformed\_request</th><td>Incorrect request parameters from the identity provider to Selectel after authorization on the provider side</td><td>Check the federation settings on the identity provider side</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Via OIDC protocol \{#oidc-errors}

If OIDC federation was configured incorrectly, errors may occur during federated user authentication. Error groups:

* OIDC001 — OIDC099 – federation configuration errors on the Selectel side;
* OIDC100 — OIDC199 – OIDC protocol validation errors on the identity provider side;
* OIDC200 — OIDC299 – other errors.

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Error</th><th>Cause</th><th>Solution</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <th colspan="3">OIDC001 – OIDC099 — federation configuration errors on the Selectel side</th>
      </tr>

      <tr>
        <th>OIDC001: oidc\_idp\_not\_configured</th><td>OIDC-compatible provider was not added on the Selectel side</td><td>Check the federation settings on the Selectel side</td>
      </tr>

      <tr>
        <th>OIDC002: oidc\_jwks\_uri\_not\_configured</th><td>JWKS URI for verifying token signatures is not added to the federation in Selectel</td><td>Specify the JWKS URI in the federation settings. You can obtain the JWKS URI from the identity provider's Discovery Document, which is available at `https://<idp_url>/.well-known/openid-configuration`. Specify `<idp_url>` — your identity provider URL</td>
      </tr>

      <tr>
        <th colspan="3">OIDC100 – OIDC199 — OIDC protocol validation errors on the identity provider side</th>
      </tr>

      <tr>
        <th>OIDC100: oidc\_authorization\_error</th>

        <td>
          The Identity Provider returned an error during the authorization phase. Possible reasons:

          * user rejected the authorization request;
          * client is not authorized for this type of authorization;
          * requested Permitted scope is not supported;
          * internal error on the identity provider side
        </td>

        <td>
          Check client settings at the identity provider and ensure that;

          * selected Grant Type is `Authorization Code`;
          * the correct Permitted scope is specified (at least `openid`);
          * the user has access to the application
        </td>
      </tr>

      <tr>
        <th>OIDC101: oidc\_state\_mismatch</th>

        <td>
          The **state** parameter does not match the value sent in the authentication request. Possible reasons:

          * repeated authentication attempt within a single request;
          * the authentication time limit has expired
        </td>

        <td>Navigate to the authentication page from the Selectel Control panel again and authorize</td>
      </tr>

      <tr>
        <th>OIDC102: oidc\_token\_request\_failed</th>

        <td>
          Error while exchanging the authorization code for tokens. Possible reasons:

          * incorrect values for the **Client ID** or **Client Secret** fields;
          * authorization code expired or was used repeatedly
        </td>

        <td>Check the values of the **Client ID** and **Client Secret** fields in the federation settings on the Selectel side and ensure they match those registered at the identity provider</td>
      </tr>

      <tr>
        <th>OIDC103: oidc\_invalid\_signature</th>

        <td>
          The ID Token signature is invalid. Possible reasons:

          * the identity provider returned an incorrect ID Token value;
          * an incorrect JWKS URI is specified for the federation in Selectel;
          * public key with the specified ID not found in JWKS
        </td>

        <td>
          For an incorrect JWKS URI: specify the correct JWKS URI in the federation settings.

          For key rotation: ensure that old keys are available in JWKS during the transition period
        </td>
      </tr>

      <tr>
        <th>OIDC104: oidc\_invalid\_token\_format</th><td>Incorrect ID Token format. The identity provider returned a response that does not comply with the JWT format</td><td>Check the federation settings on the identity provider side</td>
      </tr>

      <tr>
        <th>OIDC105: oidc\_token\_expired</th><td>ID Token has expired</td><td>Navigate to the authentication page from the Selectel Control panel again and authorize</td>
      </tr>

      <tr>
        <th>OIDC106: oidc\_invalid\_audience</th><td>Audience (`aud` claim) in the ID Token does not contain the Client ID value</td>

        <td>
          * check client settings at the identity provider;
          * ensure that the token was issued for the Client ID specified in the federation settings in Selectel
        </td>
      </tr>

      <tr>
        <th>OIDC107: oidc\_subject\_not\_found</th><td>Subject identifier (`sub` claim) is missing or empty in the ID Token</td><td>Configure the identity provider to include the subject identifier in the ID Token</td>
      </tr>

      <tr>
        <th>OIDC108: oidc\_nonce\_mismatch</th><td>Nonce value in the ID Token does not match the one sent in the authorization request</td>

        <td>
          * navigate to the authentication page from the Selectel Control panel again and authorize;
          * check browser cookie settings
        </td>
      </tr>

      <tr>
        <th>OIDC109: oidc\_user\_not\_found</th><td>User does not exist in Selectel</td>

        <td>
          Add the user. If the user is added, make sure that the value of the **ExternalID** field for the user matches the sub claim from the ID Token
        </td>
      </tr>

      <tr>
        <th colspan="3">OIDC200 – OIDC299 — other errors</th>
      </tr>

      <tr>
        <th>OIDC200: oidc\_internal\_error</th><td>Unknown error</td><td>[Create a ticket](https://my.selectel.ru/tickets)</td>
      </tr>

      <tr>
        <th>OIDC201: oidc\_malformed\_response</th><td>Incorrect format of response from identity provider to Selectel after authentication on the provider side</td>

        <td>
          * check the federation settings on the identity provider side;
          * ensure that the response complies with the OIDC specification
        </td>
      </tr>
    </tbody>
  </table>
</CustomTable>

<Formbricks />