[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > Concepts > [Applications (SSO)](index.md) > OIDC apps

# OIDC apps


In Yandex Identity Hub, you can [create](../../operations/applications/oidc-create.md) 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](../../operations/applications/oidc-create.md#users-and-groups) to the relevant OIDC application or belonging to [user groups](../groups.md) explicitly added to it.

{% note tip %}

If you want to fine-tune user authentication in your applications, including authentication only from specific IP addresses, use [authentication policies](*authentication_policies).

{% endnote %}

[*authentication_policies]: 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](../authentication-policy.md).

OIDC apps can be managed by users with the `organization-manager.oauthApplications.admin` [role](../../security/index.md#organization-manager-oauthApplications-admin) or higher.

Every OIDC application requires an OAuth client, which is created in a user-specified [folder](../../../resource-manager/concepts/resources-hierarchy.md#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 diagram {#oidc-scheme}

The parties exchange OIDC data in [JSON](https://en.wikipedia.org/wiki/JSON) format.

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

```mermaid
sequenceDiagram
  autonumber
  actor U as Пользователь
  
  participant SP as Поставщик услуг (SP)
  participant IdP as Identity Hub (IdP)

  U ->> SP: Starting authentication
  SP ->> IdP: Sending request to IdP, redirecting the user to the authorization endpoint
  IdP ->> U: Requesting user credentials
  U ->> IdP: Entering credentials
  IdP ->> IdP: Check for OIDC application,<br/>user access, and request validity
  IdP ->> SP: Sending authorization code and redirecting the user to SP
  SP ->> IdP: Requesting ID and access tokens and sending application secret
  IdP ->> IdP: Secret validation
  IdP ->> SP: Sending the ID and access tokens
  SP ->> SP: Checking the ID token<br/>through a public key on the Yandex Cloud side
  SP ->> U: Successful authentication
```

1. The Yandex Cloud user selects SSO authentication on the external application's (service provider's) authentication page.
1. 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.
1. The user authenticates in Yandex Identity Hub with their credentials.
1. 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.
1. At the address specified in the `Token endpoint` field, the service provider requests an [ID token](../../../iam/concepts/authorization/id-token.md) and access token from Yandex Identity Hub. The request contains the [app secret](#oidc-secret), which Yandex Identity Hub uses to verify the request.
1. If the service provider sent a valid secret, Yandex Identity Hub sends an ID token and access token to the service provider.
1. The service provider checks the received ID token using a public key that it [got](https://auth.yandex.cloud/oauth/jwks/keys) 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.

{% note info %}

The diagram shows the interaction between the parties when using an OIDC app of the [Web Application](#oidc-web) type. When using the [Single-Page Application](#oidc-single-page) and [Native Application](#oidc-native) app types, the steps of app secret query and verification are excluded from the process.

{% endnote %}

## Types of OIDC apps in Yandex Identity Hub {#oidc-application-types}

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

* [Web Application](#oidc-web)
* [Single-Page Application](#oidc-single-page)
* [Native Application](#oidc-native)

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

{% note info %}

Currently, you can only create and manage OIDC apps of the `Single-Page Application` and `Native Application` [types](oidc.md#oidc-application-types) via the [Cloud Center UI](https://center.yandex.cloud/organization).

{% endnote %}

### Web Application apps {#oidc-web}

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](#oidc-secret) can be safely stored.

`Web Application` apps support the application secret: depending on setup, the secret can be [provided](#secret-delivery) 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](#pkce) security extension; however, you can turn off this requirement in app settings.

The [Redirect URI](#oidc-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 apps {#oidc-single-page}

OIDC apps of the `Single-Page Application` type are optimized for user authentication to external [SPA](https://en.wikipedia.org/wiki/Single-page_application) applications. SPA applications are typically in-browser apps built on the [JavaScript](https://en.wikipedia.org/wiki/JavaScript) or [TypeScript](https://www.typescriptlang.org/) frameworks ([React](https://react.dev/), [Vue](https://vuejs.org/), [Angular](https://angular.dev/), 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](#pkce) security extension, and you cannot turn off this requirement in app settings.

The [Redirect URI](#oidc-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 apps {#oidc-native}

OIDC apps of the [Native Application](oidc.md#oidc-native) 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](#pkce) security extension, and you cannot turn off this requirement in app settings.

The [Redirect URI](#oidc-redirect-uri) of `Native Application` apps supports any valid URI scheme.

## OIDC app secret {#oidc-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](#oidc-web) apps. No application secret is used in [Single-Page Application](#oidc-single-page) and [Native Application](#oidc-native) 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](../../operations/applications/oidc-update.md#update-secret) any number of new secrets in the app at any time or delete them.

{% note warning %}

Once a secret is deleted in the OIDC app, remember to provide a new secret in the integration settings on the service provider side.

{% endnote %}

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 secret {#secret-delivery}

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.

## PKCE {#pkce}

[PKCE](https://www.rfc-editor.org/info/rfc7636/) (_Proof Key for Code Exchange_) is a security extension used in [OAuth 2.0](https://www.rfc-editor.org/info/rfc6749/) to minimize the risk of authentication data interception.

By default, OIDC apps of all [types](#oidc-web) 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](#oidc-web) apps, this requirement can be turned off. You cannot turn off the PKCE requirement for [Single-Page Application](#oidc-single-page) and [Native Application](#oidc-native) apps.

## Identity provider (Yandex Identity Hub) side setup {#oidc-idp-setup}

For the integration to work correctly on the Yandex Identity Hub side, you need to [specify](../../operations/applications/oidc-create.md#setup-idp) the [redirect URI](#oidc-redirect-uri) address (addresses) in the OIDC app, select user [attributes](#oidc-user-attributes) to send to the service provider, and generate an [app secret](#oidc-secret). Before configuring your OIDC application in Yandex Identity Hub, get the redirect URI address (addresses) from your service provider.

### Redirect URI {#oidc-redirect-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](#oidc-web) and [Single-Page Application](#oidc-single-page) 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](#oidc-native) apps, [Redirect URIs](#oidc-redirect-uri) support any valid URI schema.

You can specify several Redirect URI addresses in your OIDC apps at the same time.

### User attributes {#oidc-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](../groups.md) 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 setup {#oidc-sp-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](../../operations/applications/oidc-create.md#setup-sp) 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](https://center.yandex.cloud/organization/apps). 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](#oidc-secret) on the service provider side when configuring integration with [Web Application](#oidc-web) apps.

#### Useful links {#see-also}

* [Creating an OIDC application in Yandex Identity Hub](../../operations/applications/oidc-create.md)
* [Updating an OIDC application in Yandex Identity Hub](../../operations/applications/oidc-update.md)
* [Deactivating and deleting an OIDC application in Yandex Identity Hub](../../operations/applications/oidc-deactivate-remove.md)
* [Authentication and authorization security checklist](../../../security/domains/iam-checklist.md)
* [SAML apps](saml.md)