OAuth Setup

DHMAD supports OAuth 2.0 for Single Sign-On (SSO) integration, allowing users to authenticate with their DHMAD accounts in your application.

Overview

OAuth 2.0 allows your application to:

Authenticate users with their DHMAD accounts
Access user information (with permission)
Provide seamless SSO experience

Getting Your OAuth Credentials

Log into the Developer Dashboard
Navigate to the “OAuth Client Credentials” section
Copy your Client ID and Client Secret

Keep your Client Secret secure! Never expose it in client-side code or commit it to version control.

Configuring Redirect URIs

Redirect URIs must be full URLs including a path. During authorization, the redirect_uri parameter must exactly match one of your registered URIs.

https://example.com/callback
https://example.com/auth/dhmad/callback

Domain-only URIs (e.g., https://example.com) are not accepted. You must include a path such as /callback or /auth/callback. Each redirect URI is matched exactly — no wildcard or pattern matching is performed.

OAuth Flow

The OAuth 2.0 authorization code flow with PKCE:

Authorization Request - Redirect user to authorization endpoint (the state parameter is required)
Consent Screen - User sees which application is requesting access and what permissions (scopes) are being requested
User Authentication - User logs in with their DHMAD account
Authorization - User authorizes the application
Authorization Code - User is redirected back with code and state
Token Exchange - Exchange code for access token
User Info - Use access token to get user information

The state parameter is required. Requests without a state parameter will be rejected with an invalid_request error. Generate a unique, random value for each authorization request and validate it on the callback to prevent CSRF attacks.

Implementation Example

// Step 1: Generate PKCE challenge and state
import crypto from 'crypto';

function generatePKCE() {
  const codeVerifier = crypto.randomBytes(32).toString('base64url');
  const codeChallenge = crypto
    .createHash('sha256')
    .update(codeVerifier)
    .digest('base64url');
  
  return { codeVerifier, codeChallenge };
}

// Step 2: Redirect to authorization
const { codeVerifier, codeChallenge } = generatePKCE();
sessionStorage.setItem('code_verifier', codeVerifier);

// state is REQUIRED — generate a random value and store it for validation
const state = crypto.randomBytes(16).toString('hex');
sessionStorage.setItem('oauth_state', state);

const params = new URLSearchParams({
  client_id: CLIENT_ID,
  redirect_uri: REDIRECT_URI,
  response_type: 'code',
  scope: 'openid profile email',
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
  state
});

window.location.href = `https://dhmad.tn/api/oauth/authorize?${params}`;

// Step 3: Handle callback — validate state before using the code
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const returnedState = urlParams.get('state');

if (returnedState !== sessionStorage.getItem('oauth_state')) {
  throw new Error('Invalid state parameter — possible CSRF attack');
}

// Step 4: Exchange code for token
const tokenResponse = await fetch('https://dhmad.tn/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code,
    redirect_uri: REDIRECT_URI,
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    code_verifier: sessionStorage.getItem('code_verifier')
  })
});

const tokens = await tokenResponse.json();

// Step 5: Get user info
const userResponse = await fetch('https://dhmad.tn/api/oauth/userinfo', {
  headers: {
    'Authorization': `Bearer ${tokens.access_token}`
  }
});

const user = await userResponse.json();

import secrets
import hashlib
import base64
import requests

# Step 1: Generate PKCE
def generate_pkce():
    code_verifier = base64.urlsafe_b64encode(
        secrets.token_bytes(32)
    ).decode('utf-8').rstrip('=')
    
    code_challenge = base64.urlsafe_b64encode(
        hashlib.sha256(code_verifier.encode()).digest()
    ).decode('utf-8').rstrip('=')
    
    return code_verifier, code_challenge

# Step 2: Authorization URL
code_verifier, code_challenge = generate_pkce()
session['code_verifier'] = code_verifier

# state is REQUIRED — generate a random value and store it for validation
state = secrets.token_urlsafe(16)
session['oauth_state'] = state

auth_url = 'https://dhmad.tn/api/oauth/authorize'
params = {
    'client_id': CLIENT_ID,
    'redirect_uri': REDIRECT_URI,
    'response_type': 'code',
    'scope': 'openid profile email',
    'code_challenge': code_challenge,
    'code_challenge_method': 'S256',
    'state': state
}

# Redirect user to: f"{auth_url}?{urlencode(params)}"

# Step 3: Handle callback — validate state before using the code
if request.args.get('state') != session.get('oauth_state'):
    raise ValueError('Invalid state parameter')

code = request.args.get('code')
token_response = requests.post(
    'https://dhmad.tn/api/oauth/token',
    json={
        'grant_type': 'authorization_code',
        'code': code,
        'redirect_uri': REDIRECT_URI,
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'code_verifier': session['code_verifier']
    }
)

tokens = token_response.json()

# Step 4: Get user info
user_response = requests.get(
    'https://dhmad.tn/api/oauth/userinfo',
    headers={'Authorization': f"Bearer {tokens['access_token']}"}
)

user = user_response.json()

Scopes

Available OAuth scopes:

openid - OpenID Connect (required for ID token)
profile - User profile information
email - User email address

Security Best Practices

DHMAD only supports the S256 code challenge method for PKCE. The plain method is not accepted and will be rejected with an invalid_request error. Always use SHA-256 to hash your code verifier.

Use PKCE (S256)

Always use PKCE with the S256 code challenge method (plain is not supported)

HTTPS Only

Always use HTTPS for redirect URIs in production

State is Required

The state parameter is mandatory. Requests without it are rejected. Generate a unique random value per request and validate it on callback to prevent CSRF attacks.

Secure Storage

Store tokens securely, never in localStorage for sensitive apps

When a user is redirected to the authorization endpoint, they are shown a consent screen that displays:

Your application name (as registered in the Developer Dashboard)
Requested permissions (scopes) with clear descriptions of what data will be shared

The user must explicitly authorize the request before an authorization code is issued. If the user clicks “Cancel”, they are redirected back to your redirect_uri with error=access_denied.

Client Info Endpoint

You can retrieve public information about an OAuth client (useful for pre-flight checks):

curl https://dhmad.tn/api/oauth/client-info?client_id=YOUR_CLIENT_ID

Response:

{
  "name": "Your Application Name",
  "scopes": ["openid", "profile", "email"]
}

This endpoint is public and does not require authentication. It returns only the client name and allowed scopes.

Discovery Endpoint

Get OAuth configuration:

curl https://dhmad.tn/.well-known/openid-configuration

Support

For OAuth integration help, contact support@dhmad.tn

OAuth credentials are automatically generated when you first access your developer dashboard. You can regenerate your client secret at any time.

Get Started

API Reference

Guides

Developer Portal

Overview

Getting Your OAuth Credentials

Configuring Redirect URIs

OAuth Flow

Implementation Example

Scopes

Security Best Practices

Use PKCE (S256)

HTTPS Only

State is Required

Secure Storage

Client Info Endpoint

Discovery Endpoint

Support

​Overview

​Getting Your OAuth Credentials

​Configuring Redirect URIs

​OAuth Flow

​Implementation Example

​Scopes

​Security Best Practices

Use PKCE (S256)

HTTPS Only

State is Required

Secure Storage

​Consent Screen

​Client Info Endpoint

​Discovery Endpoint

​Support

Overview

Getting Your OAuth Credentials

Configuring Redirect URIs

OAuth Flow

Implementation Example

Scopes

Security Best Practices

Consent Screen

Client Info Endpoint

Discovery Endpoint

Support