OIDC Dynamic Client Registration — Automating Provider Onboarding

In this tutorial, you will learn about OIDC Dynamic Client Registration. We cover key concepts, practical examples, and best practices to help you master this topic.

Dynamic Client Registration in Openid Connect allows a client application to register itself with an OIDC provider programmatically, receiving a client_id and client_secret without manual provider-side configuration.

What You'll Learn

• What dynamic client registration is and when to use it
• How to send a registration request and Process the response
• Security considerations for automated registration

Why It Matters

Manual client registration requires provider admin access and creates friction for developers. With dynamic registration, a developer can register their app with any OIDC provider instantly, enabling seamless developer onboarding and CI/CD pipeline automation.

Real-World Use

DodaTech's API partner program allows third-party developers to integrate with Doda authentication. Instead of submitting a support ticket for client credentials, partners call the dynamic registration endpoint and receive their client_id immediately, reducing onboarding from days to seconds.

flowchart LR
    A["Developer App"] -->|"POST /register\n(client metadata)"| B["OIDC Provider"]
    B -->|"client_id + client_secret"| A
    A -->|"Use credentials\nto authenticate"| B
    style B fill:#dbeafe,stroke:#2563eb
    style A fill:#fef3c7,stroke:#d97706

Registration Request

Send a POST request to the provider's registration endpoint with client metadata:

import requests
import json

registration_endpoint = "https://accounts.example.com/connect/register"

client_metadata = {
    "client_name": "Doda Browser Integration",
    "redirect_uris": [
        "https://doda.example.com/callback",
        "https://doda.example.com/callback-alt"
    ],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "client_secret_basic",
    "scope": "openid profile email",
    "application_type": "web",
    "subject_type": "pairwise"
}

response = requests.post(
    registration_endpoint,
    json=client_metadata
)

if response.status_code == 201:
    client_info = response.json()
    print(f"Client ID: {client_info['client_id']}")
    print(f"Client Secret: {client_info['client_secret']}")
    print(f"Client ID Issued At: {client_info['client_id_issued_at']}")
else:
    print(f"Registration failed: {response.text}")

Expected output:

Client ID: 7x3k9m2n8q1f4d2h
Client Secret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Client ID Issued At: 1719876543

Registration Response

The provider returns a client_id, optionally a client_secret, and any registered metadata:

{
  "client_id": "7x3k9m2n8q1f4d2h",
  "client_secret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "client_id_issued_at": 1719876543,
  "client_secret_expires_at": 0,
  "registration_client_uri": "https://accounts.example.com/connect/register?client_id=7x3k9m2n8q1f4d2h",
  "registration_access_token": "reg-token-abc123",
  "token_endpoint_auth_method": "client_secret_basic",
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"]
}

Updating and Deleting Registration

Use the registration client URI and access token to update or delete the registration:

# Read current registration
read_response = requests.get(
    client_info["registration_client_uri"],
    headers={"Authorization": f"Bearer {client_info['registration_access_token']}"}
)

# Update registration (e.g., add a redirect URI)
update_payload = client_metadata.copy()
update_payload["redirect_uris"].append("https://doda.example.com/new-callback")

update_response = requests.put(
    client_info["registration_client_uri"],
    json=update_payload,
    headers={"Authorization": f"Bearer {client_info['registration_access_token']}"}
)

# Delete registration
delete_response = requests.delete(
    client_info["registration_client_uri"],
    headers={"Authorization": f"Bearer {client_info['registration_access_token']}"}
)

Common Mistakes

1. Not Securing the Registration Access Token

The registration access token allows full control over the client registration. Store it securely alongside the client secret.

2. Sending Metadata the Provider Does Not Support

Check the provider's discovery document for supported metadata fields. Unsupported fields are silently ignored.

3. Using Dynamic Registration for Production Without Considering Rate Limits

Providers typically rate-limit registration endpoints. A CI/CD pipeline creating a client per deployment may hit limits.

4. Not Handling client_secret_expires_at

Some providers expire client secrets. Implement secret rotation when client_secret_expires_at is non-zero.

5. Confusing client_id_issued_at with client_secret_expires_at

The client_id_issued_at is a timestamp for when the client was created. client_secret_expires_at (0 = never expires) controls secret expiration.

Practice Questions

1. What HTTP method is used for dynamic client registration?
2. What status code indicates successful registration?
3. How do you update a registered client's metadata?
4. What is the registration access token used for?
5. What happens if you send unsupported metadata?

Answers

1. POST to the registration endpoint. 2. 201 Created. 3. Send a PUT request to the registration client URI with the registration access token. 4. It authenticates read, update, and delete operations on the registration. 5. Unsupported fields are silently ignored.

Challenge

Build a command-line tool that accepts client metadata as a JSON file, sends a dynamic registration request to a given provider, saves the returned credentials to a local config file, and supports updating and deleting registrations.

FAQ

Mini Project

Create a Python Flask application with a complete dynamic client registration flow: a registration page that submits metadata to a provider, a dashboard to view all registered clients, and functionality to update redirect URIs and delete registrations.

What's Next

• Learn about OIDC client types for different application architectures
• Explore OIDC security best practices for production deployments
• Continue to popular OIDC providers comparison for choosing the right platform