Keycloak 19 және одан кейінгі нұсқасын реттеу

Яндекс 360 сервистеріне Keycloak арқылы бірыңғай кіруді (SSO) ұйымдастыру үшін SAML қолданбасын алдын ала жасап, реттеу керек.

1-қадам. SAML қолданбасын жасаңыз және реттеңіз

Keycloak әкімшісінің аккаунтына кіріңіз.
Басқару консолін ашыңыз — Administration Console опциясын басыңыз.
SAML қолданбасын жасап, оны реттеңіз:
1. Сол жақтағы панельде Clients опциясын таңдап, Create Client түймесін басыңыз.
2. Client ID өрісіне https://yandex.ru/ (соңғы жағында міндетті түрде қиғаш сызықпен) параметрін енгізіңіз.
3. Client type өрісінде SAML мәнін көрсетіп, Save түймесін басыңыз.
4. Name өрісінде қолданбаның атауын, мысалы, yandex360 көрсетіңіз.
5. Root URL өрісіне Service URL: https://passport.yandex.ru/auth/sso/commit параметрін енгізіңіз.
6. Valid Redirect URIs өрісіне Service URL енгізіңіз: https://passport.yandex.ru/auth/sso/commit және https://passport.yandex.com/auth/sso/commit.
7. IDP Initiated SSO Relay State және Master SAML Processing URL өрістерінде Service URL параметрін енгізіңіз: https://passport.yandex.ru/auth/sso/commit.
8. Әдепкі бойынша толтырылған опцияларды (Enabled, Include AuthnStatement, Sign Documents және т.б.), өзгеріссіз қалдырыңыз.
9. Name ID Format ретінде email параметрін таңдаңыз. Таңдалған опцияны Яндекс 360 параметрлеріне қарамастан беру үшін, Force Name ID format опциясын қосыңыз.
  
  Ескерту
  
  NameID төлсипатының мәнін өзгерту мүмкін емес — ол Яндекс ID жүйесінде пайдаланушыны анықтау үшін қолданылады. Егер UPN мәнін өзгертсеңіз, NameID ретінде LDAP каталогінде өзгермейтін пайдаланушы төлсипаттарының бірін көрсетіңіз.
  
  Егер реттелетін NameID қажет болса, оны пайдаланушы төлсипаттарын салыстыру параметрлерінде әдепкі бойынша орнатыңыз: Client Scopes қойындысында, жасалатын клиентке сәйкес келетін, мысалы, https://yandex.ru/-dedicated сияқты Client scope параметрін ашыңыз,Mappers мәзірінде жаңа User Attribute Mapper For NameID параметрін жасаңыз (Add mapper — By configuration).
10. Егер қызметкерлеріңіз Яндекс 360 сервистерін тек орыс тілінде ғана пайдаланбайтын болса, Valid Redirect URIs өрісінде қосымша соңғы нүктелер ретінде тілдік домендердің URL мекенжайларын қосыңыз.
  
  Тілдік домендерге арналған соңғы нүктелер:
  - https://passport.yandex.com/auth/sso/commit — ағылшын тілі үшін;
  - https://passport.yandex.kz/auth/sso/commit — қазақ тілі үшін;
  - https://passport.yandex.uz/auth/sso/commit — өзбек тілі үшін;
  - https://passport.yandex.com.tr/auth/sso/commit — түрік тілі үшін;
  Толық тізім
  - 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. Save түймесін басыңыз.
12. Signing keys config бөліміндегі Keys қойындысында Client Signature Required опциясы қосулы болса, оны өшіріп, Save түймесін тағы бір рет басыңыз.

2-қадам. Пайдаланушылардың төлсипаттарын салыстыруды реттеңіз

Client scopes қойындысында жасалатын клиентке, мысалы, https://yandex.ru/-dedicated сәйкес келетін Client scope параметрін ашыңыз.
Scope қойындысында Full Scope Allowed опциясын өшіріңіз.
Mappers қойындысына өтіп, Add Mapper түймесін басыңыз және By Configuration тармағын таңдаңыз.
Ашылған терезеде User Property тармағын таңдаңыз.
Қажетті төлсипаттарды кезекпен жасаңыз:
- X500 email — электрондық пошта мекенжайы;
- X500 surname — тегі;
- X500 givenName — аты.
Keycloak және Яндекс 360 төлсипаттарын синхрондауды реттеңіз: әрбір төлсипатты ашып, SAML Attribute Name мәнін өзгертіңіз. Яндекс 360 қолдау көрсететін SAML мәндері төменде келтірілген.

SAML Attribute Name

Value

User.EmailAddress

X500 email

User.Firstname

X500 givenName

User.Surname

X500 surname

Нәтижесінде төлсипаттарды салыстыру келесідей көрсетіледі:

SAML жауабы келесі түрде болуы тиіс:

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

3-қадам. Яндекс 360 қызметіне жіберу қажет деректерді жинаңыз

Кіру бетінің URL мекенжайы

Кіру нүктесінің мекенжайы.

Алу үшін:

1. Басқару консоліндегі сол жақ панельде Realm Settings опциясын таңдап, SAML 2.0 Identity Provider Metadata сілтемесін басыңыз.

2. Қажетті мән Location өрісінде орналасқан, оны көшіріп алыңыз.

Куәліктер жеткізушісінің баспагері

Доменнің Entity ID мәні.

Кіру бетінің URL мекенжайы сияқты алуға болады. Қажетті мән entityID өрісінде орналасқан.

Тексеру сертификаты

X.509 форматындағы токендер қолтаңбасының сертификаты.

Кіру бетінің URL мекенжайы сияқты алуға болады. Қажетті мән X509Certificate өрісінде орналасқан.

Сонымен қатар сертификатты Keys қойындысынан көшіріп алуға болады:

1. RS256 жолына өтіңіз.

2. Certificate мазмұнын көшіріп алыңыз.

Егер сізде екі белсенді токен қолтаңба сертификаты болса және қазір қандай сертификат қолданылатынына сенімді болмасаңыз, екінші сертификат үшін ұқсас әрекеттерді қайталаңыз.

Осыдан кейін Бизнеске арналған Яндекс 360 реттеуіне өтіңіз.

Реттеуге қатысты мәселелерді шешу

Егер куәліктер жеткізушісін реттеу процесі кезінде қате мәндер орнатылса, SSO арқылы кіруге тырысқанда, сіз «Авторизация орындалмады» хабарын және қате кодын көресіз:

email.no_in_response

: Төлсипаттардың атауларын User.Firstname, User.Surname, User.EmailAddress форматында көрсетіңіз. Басқа форматты, мысалы, Firstname орнатсаңыз, авторизациядан өту мүмкін болмайды.

request_your_admin

: Ұйымыңыздың пайдаланушылар каталогінің әкімшісі аккаунт үшін Яндекс 360 қызметін пайдалану мүмкіндігін шектесе, қате пайда болады. Толық ақпарат алу үшін ұйымыңыздың техникалық қолдау көрсету мамандарына хабарласыңыз.

samlresponse.invalid

: Қате кіру бетінің URL мекенжайы, куәлік жеткізушісінің баспагері немесе тексеру сертификаты дұрыс көрсетілмеген кезде орын алады. Ол сондай-ақ тексеру сертификаты біткенге дейін 14 күн ішінде немесе осы мерзімнен кейін пайда болуы мүмкін. Бизнеске арналған Яндекс 360 қызметіндегі SSO реттеулерінің дұрыстығын тексеріңіз.

unsupportable_domain

: SAML response ішіндегі User.EmailAddress пошта төлсипатының домені негізгі доменмен немесе Яндекс 360 ұйымының алиас доменімен бірдей екенін тексеріңіз. Егер олар сәйкес келмесе, қате туралы хабар көрсетіледі.

Қолдау қызметіне жазу

Мақала пайдалы болды ма?

Алдыңғы

Keycloak 18-нұсқасын реттеу

Келесі

Avanpost FAM реттеу

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