OIDC apps

In Yandex Identity Hub, you can create OpenID Connect (OIDC) applications that allow configuring OIDC-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 OIDC 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.

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 creating and deleting an OIDC app, respectively.

OIDC collaboration diagramOIDC collaboration diagram

The parties exchange OIDC data in JSON format.

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 Yandex Identity Hub (identity provider) and redirects the user to the Yandex Identity Hub's login URL specified in the Authorization endpoint field.
3. The user authenticates in Yandex Identity Hub with their credentials.
4. If Yandex 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, Yandex 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 Yandex Identity Hub. The request contains the app secret, which Yandex Identity Hub uses to verify the request.
6. If the service provider sent a valid secret, Yandex 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.

Types of OIDC apps in Yandex Identity HubTypes of OIDC apps in Yandex Identity Hub

Depending on their presets, Yandex Identity Hub OIDC apps can be of one of these types:

• Web Application
• Single-Page Application
• Native Application

You select the type when creating the app; once the app is created, you cannot change its type.

Web Application appsWeb Application apps

OIDC apps of the Web Application type are optimized for user authentication to external web apps with a server end (backend), where the application secret can be safely stored.

Web Application apps support the application secret: depending on setup, the secret can be provided in the Authorization: Basic HTTP header and/or the body of the POST request. By default, apps are set up to provide the secret via all available methods.

By default, Web Application apps require service providers to use the PKCE security extension; however, you can turn off this requirement in app settings.

The Redirect URI of Web Application apps 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).

Single-Page Application appsSingle-Page Application apps

OIDC apps of the Single-Page Application type are optimized for user authentication to external SPA applications. SPA applications are typically in-browser apps built on the JavaScript or TypeScript frameworks (React, Vue, Angular, etc.).

Single-Page Application apps do not support the use of the application secret.

Single-Page Application apps require service providers to use the PKCE security extension, and you cannot turn off this requirement in app settings.

The Redirect URI of Single-Page Application apps 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).

Native Application appsNative Application apps

OIDC apps of the Native Application type are optimized for user authentication to external mobile or desktop applications installed on their devices.

Native Application apps do not support the use of the application secret.

Native Application applications require service providers to use the PKCE security extension, and you cannot turn off this requirement in app settings.

The Redirect URI of Native Application apps supports any valid URI scheme.

OIDC app secretOIDC app secret

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

A secret can only be used in Web Application apps. No application secret is used in Single-Page Application and Native Application apps.

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.

Methods of providing the application secretMethods of providing the application secret

During user authentication, the application secret can be delivered from the service provider to the identity provider using the following methods:

• Client secret basic: The application secret is provided in the Authorization: Basic HTTP header.
• Client secret basic: The application secret is provided in the body of the POST request.

In Web Application apps, you can select one or both methods at the same time.

In Single-Page Application and Native Application apps, no secret is used; therefore, no secret delivery method can be configured.

PKCEPKCE

PKCE (Proof Key for Code Exchange) is a security extension used in OAuth 2.0 to minimize the risk of authentication data interception.

By default, OIDC apps of all types require the service provider to use the PKCE extension (i.e., to transmit code_challenge when requesting authorization and code_verifier when exchanging the code for tokens). For Web Application apps, this requirement can be turned off. You cannot turn off the PKCE requirement for Single-Page Application and Native Application apps.

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 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 Yandex 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 Yandex Identity Hub.

For Web Application and Single-Page Application apps, the Redirect URI must follow the https schema. You can only use an encryption-free protocol in apps of these types for testing purposes on a local host (http://127.0.0.1 and http://localhost).

In Native Application apps, Redirect URIs support any valid URI schema.

You can specify several Redirect URI addresses in your OIDC apps 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 setting.

• email address: User email address.

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

• groups (user's groups in the organization): Organization user groups to which the user getting authenticated belongs. The possible values are:

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

    The maximum number of groups 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: Of all the user's groups, the service provider will only get the ones explicitly specified in the Users and groups tab of the OIDC application.

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 parameters, you have to specify an application secret on the service provider side when configuring integration with Web Application apps.

Useful linksUseful links

• 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
• Authentication and authorization security checklist
• SAML apps