---
type: api
title: Prepare OpenID connect authentication
description: Create an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-security-oidc-prepare-authentication
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-security-oidc-prepare-authentication
products:
  - Elasticsearch
---

# Prepare OpenID connect authentication

Availability:

## Paths

- `POST` `/_security/oidc/prepare`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth)

## Description

Create an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.

The response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process.

Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.
These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

## Request Body

`application/json`

- `iss` (string) — optional
  In the case of a third party initiated single sign on, this is the issuer identifier for the OP that the RP is to send the authentication request to.
It cannot be specified when *realm* is specified.
One of *realm* or *iss* is required.
- `login_hint` (string) — optional
  In the case of a third party initiated single sign on, it is a string value that is included in the authentication request as the *login_hint* parameter.
This parameter is not valid when *realm* is specified.
- `nonce` (string) — optional
  The value used to associate a client session with an ID token and to mitigate replay attacks.
If the caller of the API does not provide a value, Elasticsearch will generate one with sufficient entropy and return it in the response.
- `realm` (string) — optional
  The name of the OpenID Connect realm in Elasticsearch the configuration of which should be used in order to generate the authentication request.
It cannot be specified when *iss* is specified.
One of *realm* or *iss* is required.
- `state` (string) — optional
  The value used to maintain state between the authentication request and the response, typically used as a Cross-Site Request Forgery mitigation.
If the caller of the API does not provide a value, Elasticsearch will generate one with sufficient entropy and return it in the response.

## Response

`application/json`

- `nonce` (string)
- `realm` (string)
- `redirect` (string)
  A URI that points to the authorization endpoint of the OpenID Connect Provider with all the parameters of the authentication request as HTTP GET parameters.
- `state` (string)
## Code Examples

#### Console

```console
POST /_security/oidc/prepare
{
  "realm" : "oidc1"
}
```

#### JavaScript

```javascript
const response = await client.security.oidcPrepareAuthentication({
  realm: "oidc1",
});
```

#### Python

```python
resp = client.security.oidc_prepare_authentication(
    realm="oidc1",
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_security/oidc/prepare" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "oidc1"
  }'
```

#### Java

```java
client.security().oidcPrepareAuthentication(o -> o
    .realm("oidc1")
);
```

#### C#

```c#
var response = await client.Security
    .OidcPrepareAuthenticationAsync(d1 => d1
        .Realm("oidc1")
    );
```

#### PHP

```php
$resp = $client->security()->oidcPrepareAuthentication([
    "body" => [
        "realm" => "oidc1",
    ],
]);
```

#### Ruby

```ruby
response = client.security.oidc_prepare_authentication(
  body: {
    "realm": "oidc1"
  }
)
```

## Response Examples

#### Oidc prepare authentication response example1

A successful response from `POST /_security/oidc/prepare`. It contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of the Authentication Request as HTTP GET parameters.

```json
{
  "redirect" : "http://127.0.0.1:8080/c2id-login?scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I&nonce=WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM&client_id=elasticsearch-rp",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}
```