Skip to content

OpenID Connect

This guide is intended for developers integrating an application with Mavryx IAM. It explains how to redirect a user to IAM, handle the callback, obtain and validate tokens, call protected APIs, refresh the session, and log the user out.

Supported flow

Mavryx supports the Authorization Code flow for public clients with PKCE:

Setting Value
Discovery URL https://iam.mavryx.emartsynergia.com/.well-known/openid-configuration
Issuer https://iam.mavryx.emartsynergia.com
Response type code
PKCE method S256
ID token signing algorithm RS256
Supported scopes openid, email, profile, mavryx.api

Public OIDC clients do not use a client secret. PKCE S256 is required for every authorization request.

Application configuration

Before implementing the flow, obtain the following values from the Mavryx team:

  • client_id
  • redirect URI
  • post-logout redirect URI
  • allowed scopes

Store them in the application's environment configuration:

OIDC_ISSUER=https://iam.mavryx.emartsynergia.com
OIDC_CLIENT_ID=<CLIENT_ID>
OIDC_REDIRECT_URI=<REDIRECT_URI>
OIDC_POST_LOGOUT_REDIRECT_URI=<POST_LOGOUT_REDIRECT_URI>
OIDC_SCOPES="openid email profile mavryx.api"

Use the discovery URL to configure an OIDC library whenever the library supports automatic provider discovery:

https://iam.mavryx.emartsynergia.com/.well-known/openid-configuration

Do not add a client secret. The redirect URI must match the configured value exactly. Request only the scopes assigned to the client; openid is mandatory and mavryx.api is needed only when calling a Mavryx API.

Authorization flow

1. Create the authorization request

Before redirecting the user, the application must generate:

  • a cryptographically random state
  • a cryptographically random nonce
  • a cryptographically random code_verifier
  • a code_challenge calculated as BASE64URL(SHA256(code_verifier))

Keep state, nonce, and code_verifier in the user's session until the callback is handled.

Redirect the browser to the authorization endpoint:

https://iam.mavryx.emartsynergia.com/oauth2/authorize
  ?client_id=<CLIENT_ID>
  &redirect_uri=<URL_ENCODED_REDIRECT_URI>
  &response_type=code
  &scope=openid%20email%20profile%20mavryx.api
  &state=<STATE>
  &nonce=<NONCE>
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256

The URL is split across lines for readability. Send it as one URL with all query parameters URL-encoded.

Mavryx authenticates the user and redirects the browser to the registered callback:

<REDIRECT_URI>?code=<CODE>&state=<STATE>

2. Validate the callback

Compare the returned state with the value saved before authorization. Reject the callback if the values do not match or if either value is missing.

3. Exchange the code for tokens

Exchange the authorization code within 60 seconds:

curl -X POST 'https://iam.mavryx.emartsynergia.com/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'redirect_uri=<REDIRECT_URI>' \
  --data-urlencode 'code=<CODE>' \
  --data-urlencode 'code_verifier=<CODE_VERIFIER>'

The redirect_uri must be identical to the value used in the authorization request. The authorization code is single-use.

Example response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "...",
  "id_token": "eyJ...",
  "scope": "openid email profile mavryx.api"
}

4. Validate the ID token

Before creating an application session, validate:

  • the RS256 signature using the jwks_uri from the discovery document
  • iss equals the configured Mavryx issuer
  • aud contains or equals the registered client_id
  • exp has not passed
  • nonce equals the value saved before authorization

Use a maintained OpenID Connect library whenever possible instead of implementing token validation manually.

User claims

Mavryx tokens include the active access context. An application can receive, among others:

  • sub — stable user identifier
  • email — user email address
  • profile_uuid — active profile identifier
  • role_code — active role code
  • organisation_uuid — active organisation, when available
  • organisation_unit_uuid — active organisation unit, when available

Do not grant access based on unverified token contents.

Calling a protected API

Send the access token in the Authorization header:

Authorization: Bearer <access_token>

Example UserInfo request:

curl 'https://iam.mavryx.emartsynergia.com/oauth2/userinfo' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

The mavryx.api scope should only be requested if the application calls a Mavryx API. A valid token does not automatically grant every permission. An API can return 403 Forbidden when the user lacks a required permission.

Refreshing the session

Mavryx currently refreshes user sessions through:

curl -X POST 'https://iam.mavryx.emartsynergia.com/v1/iam/token/refresh' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'refresh_token=<REFRESH_TOKEN>' \
  --data-urlencode 'client_id=<CLIENT_ID>'

Store refresh tokens securely. A stolen refresh token can be used to obtain new access tokens until it expires or is revoked.

Logout

Clear the application's local session and tokens, then redirect the browser to:

https://iam.mavryx.emartsynergia.com/oauth2/logout
  ?client_id=<CLIENT_ID>
  &post_logout_redirect_uri=<URL_ENCODED_POST_LOGOUT_REDIRECT_URI>

The URL is split across lines for readability. The logout endpoint accepts only a registered post-logout redirect URI.

Common errors

Error Likely cause
invalid_client Incorrect or inactive client_id
invalid_redirect_uri Redirect URI differs from the registered value
invalid_scope Missing openid or an unsupported scope
invalid_request Missing state, nonce, or PKCE S256 parameters
invalid_grant Expired/used code, wrong redirect URI, or wrong PKCE verifier
401 Unauthorized Missing, invalid, or expired access token
403 Forbidden User lacks the permission required by the API