Configure Keycloak version 19 and above

To set up single sign-on (SSO) to Yandex 360 services using Keycloak, you need to first create and configure a SAML application.

Step 1. Create and configure a SAML application

1. Log in to the Keycloak admin account.

2. Open the management console by clicking Administration Console.

3. Create a SAML application and configure it:

   1. In the panel on the left, select Clients and click Create Client.

   2. In the Client ID field, enter https://yandex.ru/ (with a slash at the end).

   3. In the Client type field, enter SAML and click Save.

   4. In the Name field, specify the name of the application (for example, yandex360).

   5. In the Root URL field, enter the Service URL: https://passport.yandex.ru/auth/sso/commit.

   6. In the Valid Redirect URIs field, enter the Service URL: https://passport.yandex.ru/auth/sso/commit and https://passport.yandex.com/auth/sso/commit.

   7. In the IDP Initiated SSO Relay State and Master SAML Processing URL fields, enter the Service URL: https://passport.yandex.ru/auth/sso/commit.

   8. Leave options that are filled in by default (Enabled, Include AuthnStatement, Sign Documents, and so on) unchanged.

   9. In the Name ID Format field, select "email". In order for the selected format to be used regardless of the Yandex 360 settings, enable the Force Name ID format option.

      Note

      The NameID value is used to identify the user in Yandex ID and cannot be changed. If you change your UPN, set one of the immutable user attributes as NameID in your LDAP directory.

      If you need a custom NameID, set it by default in the user attribute mapping settings: on the Client Scopes tab, open Client scope that corresponds to the client being created, for example: https://yandex.ru/-dedicated, and on the Mappers tab, create a new User Attribute Mapper For NameID (Add mapper – By configuration).

   10. If your employees use Yandex 360 services not only on the Russian domain, add the URLs with language-specific domains as endpoints to the Valid Redirect URIs field.

       

       Endpoints for language-specific domains:

       • https://passport.yandex.com/auth/sso/commit (for English)

       • https://passport.yandex.kz/auth/sso/commit (for Kazakh)

       • https://passport.yandex.uz/auth/sso/commit (for Uzbek)

       • https://passport.yandex.com.tr/auth/sso/commit (for Turkish)

       Full list

       • https://passport.yandex.com/auth/sso/commit

       • https://passport.yandex.az/auth/sso/commit

       • https://passport.yandex.by/auth/sso/commit

       • https://passport.yandex.co.il/auth/sso/commit

       • https://passport.yandex.com/auth/sso/commit

       • https://passport.yandex.com.am/auth/sso/commit

       • https://passport.yandex.com.ge/auth/sso/commit

       • https://passport.yandex.com.tr/auth/sso/commit

       • https://passport.yandex.ee/auth/sso/commit

       • https://passport.yandex.eu/auth/sso/commit

       • https://passport.yandex.fi/auth/sso/commit

       • https://passport.yandex.fr/auth/sso/commit

       • https://passport.yandex.kg/auth/sso/commit

       • https://passport.yandex.kz/auth/sso/commit

       • https://passport.yandex.lt/auth/sso/commit

       • https://passport.yandex.lv/auth/sso/commit

       • https://passport.yandex.md/auth/sso/commit

       • https://passport.yandex.pl/auth/sso/commit

       • https://passport.yandex.ru/auth/sso/commit

       • https://passport.yandex.tj/auth/sso/commit

       • https://passport.yandex.tm/auth/sso/commit

       • https://passport.yandex.uz/auth/sso/commit

   11. Click Save.

   12. In the Signing keys config section on the Keys tab, disable the Client Signature Required option if it is enabled, and click Save.

Step 2. Configure user attribute mapping

1. On theClient scopes tab, open Client scope, that corresponds to the client being created, for example: https://yandex.ru/-dedicated.

2. On the Scope tab, disable the Full Scope Allowed option.

3. Go to the Mappers tab, click Add Mapper and select By Configuration.

4. In the window that opens, select User Property.

5. Create the attributes one by one:

   • X500 email: Email address.

   • X500 surname: Last name.

   • X500 givenName: First name.

   

6. Set up syncing of Keycloak and Yandex 360 attributes by opening each attribute and changing the value of SAML Attribute Name. The SAML Attribute Name values that are supported in Yandex 360 are listed below.

   SAML Attribute Name	Value
   User.EmailAddress	X500 email
   User.Firstname	X500 givenName
   User.Surname	X500 surname

   The resulting attribute mapping will look like this:

   

   

   

The SAML response should look like this:

<Attribute Name="User.EmailAddress">
    <AttributeValue>email@test.com</AttributeValue>
</Attribute>
<Attribute Name="User.Surname">
    <AttributeValue>Surname</AttributeValue>
</Attribute>
<Attribute Name="User.Firstname">
    <AttributeValue>Firstname</AttributeValue>
</Attribute>

Step 3. Collect the data to be sent to Yandex 360

Login page URL

Entry point address.

To get it:

1. In the management console on the left panel, select Realm Settings and click SAML 2.0 Identity Provider Metadata.

2. Copy the value of the Location field.

Identity provider publisher

Domain entity ID.

You can get one the same way as the login page URL. It is located in the entityID field.

Verification certificate

X.509 token-signing certificate.

You can get one the same way as the login page URL. It is located in the X509Certificate field.

You can also copy the certificate from the Keys tab:

1. Go to line RS256.

2. Copy the contents of the Certificate field.

If you have two active token-signing certificates and you are not sure which certificate is currently being used, repeat the same actions for the second certificate.

After that, proceed to setting up Yandex 360 for Business.

Troubleshooting

If incorrect values were specified during the identity provider setup and you try to log in with SSO, you'll see a message that reads "Login failed" along with the error code:

email.no_in_response

Specify the attribute names in the format User.Firstname, User.Surname, User.EmailAddress. If you use a different format, such as Firstname, you will not be able to log in.

request_your_admin

The error occurs if the user directory administrator of your organization has restricted access to Yandex 360 for the account. For details, contact your organization's technical support team.

samlresponse.invalid

This error occurs if you entered an invalid login page URL, identity provider publisher, or verification certificate. Check the SSO settings in Yandex 360 for Business.

unsupportable_domain

Make sure that the domain in the User.EmailAddress mail attribute in the SAML response is the same as your primary domain or one of the alias domains of your Yandex 360 organization. If they don't match, you will get an error message.