Skip to content
Developer docs
Menu

Get started

Overview

Use Aldelo SSO to sign people in to your app with OpenID Connect.

Aldelo SSO is the sign-in service for Aldelo Cloud. Your app sends people to it to sign in, and gets back standard OpenID Connect tokens that say who they are and which organization they are working in.

How sign-in works

  1. Your app sends the browser to https://sso.aldelo.com/authorize with an authorization code request that uses PKCE.
  2. The person signs in at sso.aldelo.com and, the first time, agrees to share their details with your app. If your app serves several organizations and they belong to more than one, they choose one.
  3. SSO sends the browser back to your registered redirect URI with a one-time code.
  4. Your server exchanges the code at https://sso.aldelo.com/oauth2/token for an ID token and an access token.
  5. Your app validates the ID token and starts its own session for the person.

What you need

  • A registered application: a client_id, your exact redirect URIs and, for a server-side app, a client secret. See Request access.
  • An OpenID Connect client library that supports the authorization code flow with PKCE. Most maintained libraries do.
  • HTTPS for every redirect URI and for your back-channel logout URI.

Endpoints

Point your library at the issuer https://sso.aldelo.com. It reads everything else from the discovery document at https://sso.aldelo.com/.well-known/openid-configuration.

Endpoints a relying party calls
EndpointUse
/authorizeStart a sign-in (browser redirect).
/oauth2/tokenExchange the code for tokens (server to server).
/userinfoRead the signed-in person's claims with an access token.
/oauth2/introspectAsk whether an access token is still active.
/oauth2/revokeRevoke an access token.
/logoutSign the person out of SSO (browser redirect).
/api/v1/me/membershipsList the organizations the signed-in person belongs to.
/.well-known/jwks.jsonThe public keys that sign every token.

The API reference documents each endpoint, and OpenAPI (JSON) is the same contract in machine-readable form.

Security at a glance

  • PKCE with S256 is required on every sign-in, including sign-ins from server-side apps.
  • Redirect URIs must match a registered URI exactly. SSO never redirects to an unregistered URI; a request it can't trust shows an error page at sso.aldelo.com instead.
  • Tokens are signed with RS256. Validate them against the published keys.

Never put secrets in email

Client secrets, tokens and passwords never travel by email, in either direction. If anyone asks you to email one, don't.

Get help

Email developer@aldelo.com. If a sign-in page shows a reference code, include it: it lets us find the exact request.