Skip to content
CEagle

Signing in with CEagle

CEagle accounts is an OAuth 2.0 authorization server and an OpenID Connect provider. This is how another application uses it.

CEagle accounts is the identity provider everything in CEagle signs in against. It is also available to your application: register one, and people can sign in to it with the CEagle account they already have.

Register an applicationStart

Client id, redirect URIs, permissions and the secret you see once.

Read on
Authorization code with PKCEMost apps

Anything with a browser: web, desktop, single-page.

Read on
The device flowNo browser

How the calculator signs in.

Read on
Refresh tokensStaying signed in

Rotation, reuse detection and what to store.

Read on

Do not hard-code endpoints#

Read them from the discovery document:

curl -s https://account.ceagle.cc/.well-known/openid-configuration

A standards-compliant OpenID Connect library will do that for you given only the issuer, and will fetch the signing keys from the JWKS URL it names. Use one rather than hand-rolling the flow.

Which flow#

  1. Does the thing have a browser?

    Then use the authorization code flow with PKCE. That covers web applications, desktop applications and single-page applications alike.

  2. Does it not?

    Then use the device flow. Show a short code and a URL, and poll while the person approves it somewhere else.

  3. Is it a background job with no user?

    Then it does not sign anyone in, and none of these apply. There is no client credentials flow for reaching user data.

Client types#

confidential

A server that can keep a secret. It gets a client secret and authenticates at the token endpoint.

public

Anything that cannot: a single-page app, a mobile app, a desktop binary. No secret at all, and PKCE is mandatory.

Permissions and scopes#

The console talks about permissions, which is what a person sees on the consent screen. A permission expands into one or more OAuth scopes, which is what the token carries.

Ask for permissions when registering. Expect scopes in the token response.

curl -s https://account.ceagle.cc/api/v1/permissions
Permissions and scopes

The catalog, what each one grants, and why they are two vocabularies.

Read on

Asking for a long-lived session#

Include offline_access in the scopes and the token response carries a refresh token. Without it, the session ends when the access token expires and the person has to sign in again.

Errors look different here#

The OAuth endpoints answer with the RFC 6749 shape:

{ "error": "invalid_grant", "error_description": "the authorization code is invalid or has expired" }

Everything under /api/v1 answers with the CEagle shape:

{ "error": "validation_failed", "message": "One or more fields are invalid.", "fields": [] }

Both are stable in the error field. Neither error_description nor message is.

Accounts API reference

Every endpoint, with schemas and the flows described inline.

Read on
CEagle documentation