Projects and issuers

Understand what a project is, why its URL is the only value a client needs, and how a client finds the project's endpoints and signing keys from it.

A project is one complete identity provider. It has its own people, its own applications, its own signing keys and one URL. Everything in these docs happens inside a project, and every request you make goes to that project's URL.

This page explains the model. To see it working, follow Add sign-in to an app.

One project, one issuer

Each project has a single URL of this form:

https://<project>.authfi.io

That URL is the project's issuer: the name the project signs tokens under. It appears as the iss claim in every token the project signs. It is also the only value you configure in a client, because everything else can be read from it.

The region a project runs in is never part of the issuer.

These docs use a project called acme, whose issuer is https://acme.authfi.io.

Projects are separate

A company usually has more than one project, for example one for production and one for testing. Projects do not share users, keys or tokens. A person in one project does not exist in another, and a token signed by one project does not verify against the keys of another.

How a client finds the endpoints

A project publishes discovery documents: JSON documents at fixed paths under the issuer that list the project's endpoints and what they accept. A client reads its endpoints from these documents and does not hard-code them.

curl https://acme.authfi.io/.well-known/openid-configuration

Each document describes one part of the project.

An OpenID Connect library needs only the issuer: it fetches the first document and reads the endpoints from it. The full contents of each document are in Discovery documents.

How tokens are signed and verified

Each project signs with its own keys. A private key never leaves the project's key service. The public halves are published as a JSON Web Key Set (JWKS, RFC 7517) at /.well-known/jwks.json.

A service verifies a token in three parts. It fetches the key set and picks the key whose kid matches the kid in the token's header. It checks the signature with that key. Then it checks that iss is the issuer it trusts and that exp is in the future. Any JWT library does this when you give it the jwks_uri.

Keys and secrets covers rotation and the other keys a project holds.

Who gets access inside a project

Access in a project is granted to groups. Applications, cloud roles, servers and tools are assigned to groups, and a person or agent gets access by being in one. Adding someone to a group gives them everything that group has. Removing them takes it away.

A token carries the caller's groups in the groups claim and their roles in the roles claim. Roles, groups and grants explains the whole model.

Next steps