SAML apps

In Yandex Identity Hub, you can create SAML applications that allow configuring SAML-based single sign-on on the Yandex Identity Hub side and provide the values you need to set up integration on the service provider's side.

The external applications can only be accessed by Yandex Cloud organization users either explicitly added to the relevant SAML application or belonging to user groups explicitly added to it.

Authentication policies are a Yandex Identity Hub tool that allows you to flexibly configure access to applications by denying or allowing authentication for specific users in specific applications and/or from specific IP addresses. For more information, see Authentication policies in Yandex Identity Hub.

SAML apps can be managed by users with the organization-manager.samlApplications.admin role or higher.

SAML collaboration diagramSAML collaboration diagram

The basic concept of user authentication via SAML-based single sign-on is as described below:

1. The Yandex Cloud user selects SSO authentication on the external application's (service provider's) authentication page.
2. The service provider sends a SAML request to Yandex Identity Hub (identity provider) and redirects the user to the Yandex Identity Hub's login URL. If you enable signature verification for SAML requests from the service provider, authentication will not start for as long as the request has no signature or the signature is invalid.
3. The user authenticates in Yandex Identity Hub with their credentials.
4. If Yandex Identity Hub has a SAML app corresponding to this external application, the authenticated user is added to this SAML app, and the incoming SAML request is correct, Yandex Identity Hub will send to the service provider a signed (and encrypted if the relevant option is on) SAML response containing the user's attributes.
5. The service provider checks the SAML response and its signature for correctness and, if successful, grants the user access to the external application.
6. As soon as the user logs out of the external application, the service provider sends a SAML request to Yandex Identity Hub and redirects the user to the Yandex Identity Hub's logout URL.

The parties exchange SAML data in XML format.

Identity provider (Yandex Identity Hub) side setupIdentity provider (Yandex Identity Hub) side setup

For the integration to work correctly on the Yandex Identity Hub side, you need to set up several integration parameters in your SAML application. Get the required values for these parameters from your service provider:

• SP EntityID : Unique service provider ID.

  The value must be the same on the service provider's and Yandex Identity Hub side.

• ACS URL: URL Yandex Identity Hub will send the SAML response to.

  The ACS URL must follow the https schema. You can only use an encryption-free protocol for testing purposes on a local host (http://127.0.0.1 and http://localhost values).

  If your service provider uses ACS indexes instead of ACS URLs, in addition to ACS URLs, you can specify the index value you got on the service provider's side.

  You can specify multiple URLs/ACS indexes.

  Note

  If you have specified an index for one of the URLs in the ACS URL field settings, you must also specify indexes for all the other URLs.

• Signature mode: SAML response elements that will be digitally signed:

  • Assertions: Only provided attributes will be signed. This is a default value.
  • Response: The full SAML response will be signed.
  • Assertions and Response: The full SAML response and, separately, the provided attributes will be signed.

  Warning

  The signing mode configured for the SAML app on the Yandex Identity Hub side must be the same as the signing mode on the service provider's side.

• Only accept signed requests: Allows you to verifying the signature of the service provider's SAML requests and suspend authentication if the request has no signature or the signature is invalid.

  To enable this feature, you need to upload the public key certificate you got from the service provider, which will be used for signature verification.

• Encrypt assertion in response: Allows you to enable encryption of SAML responses to add an extra data protection layer. By default, SAML responses are only signed.

  To enable this feature, you need to upload the public key certificate you got from the service provider, which will be used for encryption.

User and group attributesUser and group attributes

By default, a new SAML app is created with a specific set of user-related attributes Yandex Identity Hub will provide to the service provider. This set includes:

Attribute name	Attribute value	Provided value
NameID	SubjectClaims.preferred_username	User ID
givenname	SubjectClaims.given_name	User's full name
fullname	SubjectClaims.name	User's first name
surname	SubjectClaims.family_name	User's last name
emailaddress	SubjectClaims.email	User's email address

After you create a SAML application, you can add, modify, and delete the following user attributes:

• SubjectClaims.sub: User ID. The field value is the same as the one displayed in the ID field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., aje0fapf84ofj57q1r0b.
• SubjectClaims.preferred_username: Unique login for the user. The field value is the same as the one displayed in the Username field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., ivanov@example-federation.ru.
• SubjectClaims.name: User’s full name. The field value is the same as the one displayed in the User field in the organization's user list in the Cloud Center's Yandex Identity Hub interface. Here is an example: Ivan Ivanov.
• SubjectClaims.given_name: Name. The field value is the same as the one displayed in the Name field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: Ivan.
• SubjectClaims.family_name: Last name. The field value is the same as the one displayed in the Surname field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: Ivanov.
• SubjectClaims.email: Email address. The field value is the same as the one displayed in the Email field on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., ivanov@example-company.ru.
• SubjectClaims.phone_number: Phone number. The field value is the same as the one displayed in the Phone field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., +74951234567.
• SubjectClaims.company_name: Company name. The field value is the same as the one displayed in the Company name field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: Holiday LLC.
• SubjectClaims.department: Department name. The field value is the same as the one displayed in the Department field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: Control systems department.
• SubjectClaims.job_title: Job title. The field value is the same as the one displayed in the Job title field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: Software engineer.
• SubjectClaims.employee_id: Digital user code from the company's HR system. The field value is the same as the one displayed in the Employee ID field under Personal info on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., 08012.

You can edit format and value of the NameID attribute (user ID). The list of possible values for the Value field depends on the format you select. When you change the format, the attribute automatically resets to that format’s default value.

Possible attribute formats and values:

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress : User ID is provided in email address format. Available values:

  • SubjectClaims.preferred_username: Default value when switching to this format.

    The uniqueness and invariability of the provided ID is not guaranteed: one organization may have two users with the same preferred_username ID. For example: a federated and a local user can have the same value for this attribute.

    If the federated user's preferred_username ID is not in email format, the provided ID will be automatically suffixed with @<identity_federation_ID> to bring it to that format.

  • SubjectClaims.email: User email address.

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: User ID is provided in the organization's user ID format. In this case, the provided value is guaranteed to be unique and invariable. Available values:

  • SubjectClaims.sub: Default value when switching to this format.
  • SubjectClaims.external_id: External user ID.
  • SubjectClaims.employee_id: Employee ID.

• urn:oasis:names:tc:SAML:2.0:nameid-format:transient: User ID is provided in the current user session ID. The value of this ID changes depending on session and cannot be used to uniquely identify the user.

  You cannot explicitly specify the urn:oasis:names:tc:SAML:2.0:nameid-format:transient format in the NameID attribute's settings: the user ID comes in the SAML response in this format only if this format was explicitly requested in the SAML request.

In addition to the user attributes mentioned above, the SAML response may contain the group attribute whose value is the list of groups the user is a member of. You can specify any name and one of the following values for this attribute:

• All groups: In a SAML response, this field will include all groups the user belongs to.

  The maximum number of groups this field can include is 1,000. If the user belongs to more groups than this, only the first thousand will go to the service provider.

• Assigned groups only: In a SAML response, this field will include only those groups that are explicitly specified on the Users and groups tab of your SAML app.

Service provider (external application) side setupService provider (external application) side setup

For the integration to work correctly on the service provider's side, you need to set up a number of integration parameters. Depending on the options supported by your service provider, you can set these settings manually or automatically by uploading an XML metadata file or specifying a metadata URL.

The download link for the XML metadata file and the metadata URL are available on the app info page in the Cloud Center interface. The same page offers the integration parameter values for manual configuration:

• Issuer / IdP EntityID: Unique app ID. The value must be the same on the service provider's and Yandex Identity Hub side.
• Login URL: Address to which the service provider will send requests for user authentication.
• Logout URL: Address to which the service provider will send the SAML request when the user logs out of the system.

Additionally, the user attributes set up on the Yandex Identity Hub side must be set up and able to be correctly processed on the service provider's side.

Digital signature verification key certificateDigital signature verification key certificate

In addition to setting up the above parameters, make sure the service provider configuration includes a certificate the service provider will use to verify the digital signature Yandex Identity Hub will sign its SAML responses with.

The digital signature verification key certificate for the SAML app is automatically issued when the app is created for a five-year validity period.

If using automatic configuration via a metadata file or URL, you do not have to install the certificate manually: the metadata already contains the required certificate and it is installed automatically.

You can issue new digital signature verification key certificates for the SAML app and activate them at any time.

You must additionally specify on the service provider's side what data will be signed in the identity provider's SAML responses:

• Only the provided user attributes.
• Full SAML response.
• Full SAML response and, separately, the provided attributes.

The signing mode configured on the service provider's side must be the same as the signing mode on the Yandex Identity Hub side.

Useful linksUseful links

• Creating a SAML application in Yandex Identity Hub
• Updating a SAML app in Yandex Identity Hub
• Deactivating and deleting a SAML application in Yandex Identity Hub
• Authentication and authorization security checklist
• OIDC apps