Dipp OAuth Integration Guide

This guide provides comprehensive information for integrating with the Dipping Platform's OpenID Connect (OIDC) provider, which implements OAuth 2.0 and OpenID Connect Core 1.0 specifications.

Issuer

Development Server: https://api.dev.dipp.ing
Production Server: https://api.dipp.ing

Overview

The Dipping Platform provides a standards-compliant OpenID Connect provider that supports:

OAuth 2.0 Authorization Code Flow with PKCE support

OpenID Connect Core 1.0 for identity verification

Standard OIDC claims (sub, email, profile, etc.)

JWT-based tokens with RS256 signing

Supported Grant Types

authorization_code - Standard OAuth 2.0 authorization code flow

refresh_token - Token refresh for long-lived sessions

Supported Response Types

code - Authorization code response type

Supported Scopes

openid - OpenID Connect core scope (always included)

profile - Basic profile information (name, etc.)

email - Email address and verification status

Supported Token Endpoint Authentication Methods

client_secret_post - Client credentials in request body

client_secret_basic - Client credentials in Authorization header

Getting Started

1. OIDC Discovery

First, discover the OIDC provider's capabilities by calling the discovery endpoint:

Response:

{
  "issuer": "https://api.dipp.ing",
  "authorization_endpoint": "https://api.dipp.ing/oauth/v1/authorize",
  "token_endpoint": "https://api.dipp.ing/oauth/v1/token",
  "userinfo_endpoint": "https://api.dipp.ing/oauth/v1/userinfo",
  "revocation_endpoint": "https://api.dipp.ing/oauth/v1/revoke",
  "jwks_uri": "https://api.dipp.ing/oauth/v1/jwks",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "profile", "email"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "subject_types_supported": ["public"],
  "prompt_values_supported": ["none", "login", "consent"]
}

2. Client Registration

Note: Client registration is handled internally by the platform administrators. Contact the platform team to register your OAuth client.

Required client information:

Client name

Redirect URIs (must be pre-registered)

By default, client scopes will set to openid profile email.

OAuth 2.0 Authorization Code Flow

Step 1: Authorization Request

Redirect users to the authorization endpoint to initiate the OAuth flow:

Required Parameters:

response_type - Must be code

client_id - Your registered client ID

redirect_uri - Must match a pre-registered redirect URI

Optional Parameters:

scope - Space-separated list of requested scopes (default: openid)

state - Opaque value to maintain state between request and callback

nonce - String to associate client session with ID token

prompt - Space-separated list of prompt values:

none - No UI interaction (fails if user not authenticated)

login - Force re-authentication

consent - Show consent screen

code_challenge - PKCE code challenge (S256 method)

code_challenge_method - PKCE method (must be S256)

Example:

The user will be redirected to:

Login page (if not authenticated)

Consent page (if consent required for requested scopes)

Authorization completion (if already authenticated and consented)

Step 3: Authorization Response

Upon successful authorization, the user is redirected back to your redirect_uri with:

Success Response:

https://myapp.com/callback?code=AUTH_CODE&scope=openid profile email&state=abc123

Error Response:

https://myapp.com/callback?error=access_denied&error_description=User denied access&state=abc123

Token Management

Exchanging Authorization Code for Tokens

Exchange the authorization code for access and refresh tokens:

Required Parameters:

grant_type - Must be authorization_code

code - Authorization code from previous step

client_id - Your client ID

client_secret - Your client secret

redirect_uri - Must match the redirect URI used in authorization

Optional Parameters:

code_verifier - PKCE code verifier (required if code_challenge was used)

Authentication Options:

Option 1: Client Secret in Body (client_secret_post)

Option 2: Client Secret in Header (client_secret_basic)

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_HERE",
  "scope": "openid profile email"
}

Refreshing Access Tokens

Use the refresh token to obtain new access tokens:

Response:

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "openid profile email"
}

Token Revocation

Revoke access or refresh tokens:

Parameters:

token - The token to revoke

client_id - Your client ID

client_secret - Your client secret

token_type_hint - Optional hint: access_token or refresh_token

Response: HTTP 200 (even if token was invalid, per RFC 7009)

User Information

Getting User Claims

Retrieve user information using the access token:

Option 1: Authorization Header (Recommended)

Option 2: Request Body

Response:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@example.com",
  "email_verified": true,
  "updated_at": 1640995200
}

Available Claims:

sub - Subject identifier (user ID)

given_name - First name (profile scope)

family_name - Last name (profile scope)

email - Email address (email scope)

email_verified - Email verification status (email scope)

updated_at - Last update timestamp

Error Handling

OAuth Error Responses

All endpoints return standardized OAuth error responses:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: client_id",
  "error_uri": "https://docs.dipp.ing/errors/invalid_request"
}

Common Error Codes:

invalid_request - Request is missing required parameters

invalid_client - Client authentication failed

invalid_grant - Authorization code or refresh token is invalid

invalid_scope - Requested scope is not allowed

invalid_token - Access token is invalid or expired

unauthorized_client - Client is not authorized for this grant type

access_denied - User denied the authorization request

server_error - Internal server error

temporarily_unavailable - Service temporarily unavailable

HTTP Status Codes

200 - Success

201 - Created (client registration)

204 - No Content (consent processing, token revocation)

302 - Redirect (authorization endpoint)

400 - Bad Request (invalid parameters)

401 - Unauthorized (invalid credentials)

403 - Forbidden (access denied)

500 - Internal Server Error

Integration Examples

Soon.

Support

For technical support or questions about OIDC integration:

Documentation: https://doc.withdipp.com

Support Email: enzo@withdipp.com

Dipp OAuth Integration Guide

Table of Contents#

Issuer#

Overview#

Supported Grant Types#

Supported Response Types#

Supported Scopes#

Supported Token Endpoint Authentication Methods#

Getting Started#

1. OIDC Discovery#

2. Client Registration#

OAuth 2.0 Authorization Code Flow#

Step 1: Authorization Request#

Step 2: User Authentication & Consent#

Step 3: Authorization Response#

Token Management#

Exchanging Authorization Code for Tokens#

Refreshing Access Tokens#

Token Revocation#

User Information#

Getting User Claims#

Error Handling#

OAuth Error Responses#

HTTP Status Codes#

Integration Examples#

Support#

Table of Contents

Issuer

Overview

Supported Grant Types

Supported Response Types

Supported Scopes

Supported Token Endpoint Authentication Methods

Getting Started

1. OIDC Discovery

2. Client Registration

OAuth 2.0 Authorization Code Flow

Step 1: Authorization Request

Step 2: User Authentication & Consent

Step 3: Authorization Response

Token Management

Exchanging Authorization Code for Tokens

Refreshing Access Tokens

Token Revocation

User Information

Getting User Claims

Error Handling

OAuth Error Responses

HTTP Status Codes

Integration Examples

Support