OIDC Configuration Guide
This document outlines the configuration parameters for integrating with Optare SSO using OpenID Connect.
Discovery Endpoint
We provide a standard OIDC discovery document which can be used to automatically configure most clients.
URL: /.well-known/openid-configuration
Example: https://id.optare.one/.well-known/openid-configuration
Endpoints
| Endpoint | Path | Method | Description |
|---|---|---|---|
| Authorization | /oauth/authorize | GET | Starts the OAuth 2.0 flow. |
| Token | /oauth/token | POST | Exchanges code for tokens. |
| UserInfo | /oauth/userinfo | GET | Returns user profile information. |
| JWKS | /.well-known/jwks.json | GET | Returns public keys for verifying ID tokens. |
| Revocation | /oauth/revoke | POST | Revokes access or refresh tokens. |
| Introspection | /oauth/introspect | POST | Validates a token (RFC 7662). |
| End Session | /oauth/logout | GET | Logs the user out of the SSO session. |
Parameters
Authorization Request (/oauth/authorize)
| Parameter | Required | Description |
|---|---|---|
client_id | Yes | Your application's Client ID. |
redirect_uri | Yes | Must match one of the URIs registered for your client. |
response_type | Yes | Must be code. |
scope | Yes | Space-separated list of scopes. Must include openid. |
state | Recommended | Random string to prevent CSRF. |
nonce | Yes (if openid scope is used) | Random string to associate client session with ID Token. |
code_challenge | Recommended | PKCE code challenge. |
code_challenge_method | Recommended | Must be S256 (preferred) or plain. |
Token Request (/oauth/token)
CAUTION Optare only supports
client_secret_postauthentication. You must sendclient_idandclient_secretin the POST body, not in the HTTP Authorization header.
| Parameter | Required | Description |
|---|---|---|
grant_type | Yes | authorization_code or refresh_token. |
code | Yes (for auth code) | The code received from the authorization endpoint. |
redirect_uri | Yes | Must match the one used in the authorization request. |
client_id | Yes | Your application's Client ID (must be in POST body). |
client_secret | Yes | Your application's Client Secret (must be in POST body). |
code_verifier | Yes (if PKCE used) | The verifier used to generate the challenge. |
Token Endpoint Authentication Methods:
| Method | Supported | Description |
|---|---|---|
client_secret_post | ✅ Yes | Credentials in POST body (required) |
client_secret_basic | ❌ No | HTTP Basic Auth header (not supported) |
Supported Scopes
| Scope | Description |
|---|---|
openid | Required for OIDC. Returns ID Token. |
profile | Access to name, picture, locale. |
email | Access to email address and verification status. |
offline_access | Returns a Refresh Token for long-lived access. |
address | User's address information. |
phone | User's phone number. |
Product Scopes
You can also request access to specific products. These scopes determine which licenses are returned in the UserInfo response.
crmanalyticsadminmarketingsupport
Token Handling
ID Token
The ID Token is a standard JWT signed with RS256. It contains:
iss: Issuer URLsub: User IDaud: Client IDexp,iat,auth_time: Timestampsnonce: The nonce provided in the authorization request.organization_id: The context organization ID.
Access Token
The Access Token is a JWT used to access the UserInfo endpoint and other APIs.