Manage OAuth 2.0 and OpenID Connect clients

OAuth2 clients are applications that securely authenticate with the authorization server to obtain access to an HTTP service. Confidential clients can use registered client secrets to authenticate, while public clients are unable to use registered client secrets. OAuth2 clients can be configured in a secure manner using the Ory OAuth2 and OpenID Connect product. This documentation article explains how to manage OAuth2 clients using the Ory Console, Ory SDK, Ory CLI, and Ory REST APIs.

Create OAuth2 client

To create a new OAuth2 client, use the following methods:

Ory Console
Ory CLI
Ory SDK
REST API

The Ory Console is a web-based user interface that allows you to manage OAuth2 clients. To create a new client:

Go to OAuth 2 → OAuth2 Clients in the Ory Console
Click Create OAuth2 Client and complete the form or update an existing client.
When creating a confidential client, copy the client secret when printed. It is only shown once.

ory create oauth2-client \
  --grant-type authorization_code --grant-type refresh_token  --grant-type client_credentials \
  --response-type code \
  --scope openid --scope offline_access \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://my-app.com/callback --redirect-uri http://my-other-app.com/callback

import { Configuration, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function createOAuth2Client() {
  await ory.createOAuth2Client({
    oAuth2Client: {
      grant_types: ["authorization_code", "refresh_token"],
      redirect_uris: ["https://example.com"],
      scope: "offline openid",
      token_endpoint_auth_method: "client_secret_post",
    },
  })
}

Update OAuth2 client

To update an existing OAuth2 client, use the following methods:

Ory Console
Ory CLI
Ory SDK
REST API

Go to OAuth 2 → OAuth2 Clients in the Ory Console.
Locate the client you want to update.
Click on the pen symbol to update the client's configuration.
When you are finished, scroll to the top and click Save.

ory update oauth2-client {client.id} \
  --grant-type authorization_code --grant-type refresh_token  --grant-type client_credentials \
  --response-type code \
  --scope openid --scope offline_access \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://a-new-callback

import { Configuration, OAuth2Api, OAuth2Client } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function updateOAuth2Client(
  id: string,
  update: Partial<OAuth2Client>,
) {
  // setOAuth2Client replaces all values (empty ones too),
  // which is why we include the original client.
  const { data: original } = await ory.getOAuth2Client({ id })
  await ory.setOAuth2Client({
    id,
    oAuth2Client: {
      ...original,
      ...update,
    },
  })
}

Patch OAuth2 client

To partially update an existing OAuth2 client, use the following methods:

Ory Console
Ory SDK
REST API

Go to OAuth 2 → OAuth2 Clients in the Ory Console.
Locate the client you want to update.
Click on the pen symbol to update the client's configuration.
When you are finished, scroll to the top and click Save.

import { Configuration, JsonPatch, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function patchOAuth2Client(id: string, patches: JsonPatch[]) {
  await ory.patchOAuth2Client({
    id,
    jsonPatch: [
      ...patches,
      {
        op: "replace",
        path: "owner",
        value: "New owner",
      },
    ],
  })
}

Delete OAuth2 client

To delete an existing OAuth2 client, use the following methods:

Ory Console
Ory CLI
Ory SDK
REST API

Go to OAuth 2 → OAuth2 Clients in the Ory Console.
Locate the client you want to update.
Click on pen symbol to update the client's configuration.
Scroll to the bottom and click Delete Client.

ory delete oauth2-client {client.id}

import { Configuration, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function deleteOAuth2Client(id: string) {
  await ory.deleteOAuth2Client({ id })
}

OpenID Dynamic Client Registration

OpenID Dynamic Client Registration enables automatic registration of OAuth2 clients with the authorization server. When enabled, clients can be created, retrieved, updated, patched, and deleted dynamically without manual configuration. To enable OpenID Dynamic Client Registration, use the Ory CLI:

ory patch oauth2-config $PROJECT_ID
  --replace "/oidc/dynamic_client_registration/enabled=true"

OpenID Connect dynamic registration involves the use of a registration_access_token, which is a bearer token that allows a client to make requests to the OpenID Connect dynamic registration endpoint. The token is issued by the authorization server and can only be used by the client that it was issued to.

It's important to note that the registration_access_token is a sensitive piece of information that should be kept secure. It should only be used by the client that it was issued to and should not be shared with any other parties.

Register OAuth2 and OpenID Connect clients

Use the SDK or REST API to register an OAuth2 and OpenID Connect client:

Ory SDK
REST API

import { Configuration, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function createOidcDynamicClient() {
  const { data } = await ory.createOidcDynamicClient({
    oAuth2Client: {
      grant_types: ["authorization_code", "refresh_token"],
      redirect_uris: ["https://example.com"],
      scope: "offline openid",
      token_endpoint_auth_method: "client_secret_post",
    },
  })

  console.log(data.registration_access_token) // Write this down, it is only sent once!
  console.log(data.client_id, data.client_secret /* ... */)
}

The response includes the registration_access_token which is needed to manage the client. The token will only be shown once!

Get OAuth2 and OpenID Connect clients

The GET endpoint requires the client to authenticate with the registration_access_token regardless of the token_endpoint_auth_method. It can be used to retrieve the OAuth2 and OpenID Connect client.

Ory SDK
REST API

import { Configuration, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function getOidcDynamicClient(
  id: string,
  registrationAccessToken: string,
) {
  const { data } = await ory.getOidcDynamicClient(
    {
      id,
    },
    {
      headers: {
        Authorization: `Bearer ${registrationAccessToken}`,
      },
    },
  )
}

Update OAuth2 and OpenID Connect clients

The POST endpoint requires the client to authenticate with the registration_access_token regardless of the token_endpoint_auth_method. It can be used to update the OAuth2 and OpenID Connect client.

Ory SDK
REST API

import { Configuration, OAuth2Client, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function createOidcDynamicClient(
  id: string,
  updatedClient: OAuth2Client,
) {
  const { data } = await ory.setOidcDynamicClient({
    id: id,
    oAuth2Client: {
      ...updatedClient,
      grant_types: ["authorization_code", "refresh_token"],
      // ...
    },
  })

  console.log(data.registration_access_token) // Write this down, it is only sent once!
}

Delete OAuth2 and OpenID Connect clients

The DELETE endpoint requires the client to authenticate with the registration_access_token regardless of the token_endpoint_auth_method. It can be used to delete the OAuth2 and OpenID Connect client.

Ory SDK
REST API

import { Configuration, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function deleteOidcDynamicClient(
  id: string,
  registrationAccessToken: string,
) {
  await ory.deleteOidcDynamicClient(
    {
      id,
    },
    {
      headers: {
        Authorization: `Bearer ${registrationAccessToken}`,
      },
    },
  )
}

Example OAuth2 clients

Here are some examples of creating OAuth2 clients with different options:

Client credentials

ory create oauth2-client \
  --grant-type client_credentials \
  --scope my-scope \
  --token-endpoint-auth-method client_secret_basic

Token endpoint auth method

ory create oauth2-client \
  --grant-type authorization_code \
  --response-type code \
  --scope openid \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://my-app.com/callback

Multiple redirect URIs

ory create oauth2-client \
  --grant-type authorization_code --grant-type refresh_token \
  --response-type code \
  --scope openid --scope offline_access \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://my-app.com/callback --redirect-uri http://my-other-app.com/callback

Create OAuth2 client​

Update OAuth2 client​

Patch OAuth2 client​

Delete OAuth2 client​

OpenID Dynamic Client Registration​

Register OAuth2 and OpenID Connect clients​

Get OAuth2 and OpenID Connect clients​

Update OAuth2 and OpenID Connect clients​

Delete OAuth2 and OpenID Connect clients​

Example OAuth2 clients​

Client credentials​

Token endpoint auth method​

Multiple redirect URIs​