Applications in Yandex Identity Hub

Your organization's users can authenticate in external applications using single sign-on (SSO). With this in mind, Identity Hub allows creating applications, i.e., Yandex Cloud resources containing integration settings for Yandex Identity Hub as an identity provider (IdP) on the one hand and a third-party service provider (SP) on the other.

Identity Hub supports the SAML and OpenID Connect (OIDC) single sign-on standards.

The role of service providers can be played by various SSO-enabled services, either based on the SaaS or on-premise model, e.g., Yandex 360, GitHub, GitLab, Jenkins, Jira, and many more.

SAML applicationsSAML applications

In Identity Hub, you can create SAML applications that allow configuring SAML-based single sign-on on the 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.

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 Identity Hub (identity provider) and redirects the user to the Identity Hub's login URL.
3. The user authenticates in Identity Hub with their credentials.
4. If Identity Hub has a SAML app corresponding to this external application, the authenticated user is added to this SAML app, and the received SAML request is correct, Identity Hub sends a signed SAML response containing the user's attributes to the service provider.
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 Identity Hub and redirects the user to the Identity Hub's logout URL.

The parties exchange SAML data in XML format.

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

For the integration to work correctly on the 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 Identity Hub side.

• ACS URL: URL 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 Identity Hub side must be the same as the signing mode on the service provider's side.

User and group attributesUser and group attributes

By default, a new SAML app is created with a specific set of user-related attributes 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 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 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 Identity Hub interface, e.g., 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 Identity Hub interface, e.g., 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 Identity Hub interface, e.g., 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 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 Identity Hub interface, e.g., +74951234567.

You cannot change the name of the NameID attribute in which the user ID is provided. You can change the ID format for this attribute, unless the attribute's format is explicitly specified in the service provider's SAML request. When the format changes, the attribute value changes automatically. Possible attribute formats and values:

• urn: oasis: names: tc: SAML: 1.1:nameid-format: emailAddress: User ID is provided in email address format in the SubjectClaims.preferred_username attribute. This is the default 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.

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

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 grous : 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, only the first thousand of them will be communicated 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 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 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 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 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 Identity Hub side.

OIDC appsOIDC apps

In Identity Hub, you can create OpenID Connect (OIDC) applications that allow configuring OIDC-based single sign-on on the 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 OIDC application or belonging to user groups explicitly added to it.

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

Every OIDC application requires an OAuth client, which is created in a user-specified folder and is inherently linked to the OIDC app. An OAuth client is created and deleted automatically when, respectively, creating and deleting an OIDC app.

OIDC collaboration diagramOIDC collaboration diagram

The basic concept of user authentication via OIDC-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 an authentication request to Identity Hub (identity provider) and redirects the user to the Identity Hub's login URL specified in the Authorization endpoint field.
3. The user authenticates in Identity Hub with their credentials.
4. If Identity Hub has an OIDC app mapped to this external application, the authenticated user is added to this OIDC app, and the received authentication request is correct, Identity Hub sends an authorization code to the service provider and redirects the user back to the external app.
5. At the address specified in the Token endpoint field, the service provider requests an ID token and access token from Identity Hub. The request contains the app secret, which Identity Hub uses to verify the request.
6. If the service provider sent a valid secret, Identity Hub sends an ID token and access token to the service provider.
7. The service provider checks the received ID token using a public key that it got from Yandex Cloud using the ID from the kid field of the ID token header. If the check is successful, the service provider grants the user access to the external application.

The parties exchange OIDC data in JSON format.

OIDC app secretOIDC app secret

An app secret is generated by users on the OIDC app side in Identity Hub. It is a random fixed-length string starting with the yccs__ prefix.

An app secret must be specified in the integration settings on the service provider side and will be used to verify requests coming from the service provider.

The lifetime of an OIDC app secret is unlimited. At the same time, you can generate any number of new secrets in the app at any time or delete them.

Yandex Cloud does not store OIDC app secrets, and the user can only see them when creating them. Once you refresh or close the browser page where a secret has been generated, the content of that secret becomes unavailable.

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

For the integration to work correctly on the Identity Hub side, you need to specify the redirect URI address (addresses) in the OIDC app, select user attributes to send to the service provider, and generate an app secret. Before configuring your OIDC application in Identity Hub, get the redirect URI address (addresses) from your service provider.

Redirect URIRedirect URI

Redirect URI is an address on the external application side where the user will get redirected if successfully authenticated in Identity Hub.

The redirect URI 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).

In an OIDC app, you can specify multiple redirect URI addresses at the same time.

User attributesUser attributes

In the OIDC app settings, you can specify the user attributes defined by the values selected in the Scopes field to send to the service provider in an ID token:

• openid (user ID): User ID. This is a required parameter.

• email address: User email address.

• profile (full name, first name, last name, avatar, etc.): Additional user details.

• groups (user's groups in the organization): User groups in the organization whose member the user getting authenticated is. The possible values are:

  • All grous : Security provider will get all groups the user belongs to.

    The maximum number of sent groups: 1,000. If the user belongs to more groups, only the first thousand of them will be communicated to the service provider.

  • Assigned groups only: Of all groups the user belongs to, the service provider will only get the ones explicitly specified on the Users and groups tab of the OIDC app.

In a new OIDC app, all attributes except groups are selected by default.

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 configure these settings manually or automatically by specifying a configuration URL.

A configuration URL gives the service provider the values of all settings required for configuring the integration. You can find it in the OpenID Configuration field under Service provider (SP) configuration on the OIDC app information page in the Cloud Center interface. The same page offers the integration setting values for manual configuration:

• ClientID: Unique application ID.
• Authorization endpoint: Address in Yandex Cloud to which the service provider will redirect the user for authentication.
• Token endpoint: Address to which the external application sends a request to obtain an ID token and access token.
• Userinfo endpoint: Address the external application can use to obtain user attributes.

In addition to the above-mentioned settings, you also need to specify an app secret on the service provider side.

See alsoSee also

• 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
• Creating an OIDC application in Yandex Identity Hub
• Updating an OIDC application in Yandex Identity Hub
• Deactivating and deleting an OIDC application in Yandex Identity Hub