Wanderland Core: IDP

Frontmatter

diataxis: Reference
style: ASD-STE100
method: verified against source (wanderland-core/lib/wanderland/idp)

Legend

• IDP :: the identity provider. It loads identities and it issues scoped tokens.
• identity :: an actor or a service. It holds an id, a name, a set of roles, and a set of scopes. See wanderland-core-identity.
• role :: a capability an identity may hold. The roles are the ceiling.
• scope :: a capability a token grants. The scopes are the floor for one session.
• held scope :: a scope the token carries. An authorization check reads the held scopes.
• token :: a scoped JSON Web Token. The IDP signs it with the identity's key. See wanderland-core-pki.
• attenuation :: the reduction of the requested scopes to the roles the identity holds.

The one idea

The IDP issues a scoped token for an identity. A caller requests a set of scopes. The IDP keeps the scopes the identity's roles allow, and it rejects the rest. The token carries the kept scopes, and the IDP signs it with the identity's key. That signed token is the identity a request presents at a boundary.

The scoped token is the platform's one identity form. Every wanderland service reads the same token, because the IDP, the identity, and the token all live in wanderland-core. The token is a JSON Web Token, signed RS256 with the identity's private key. The payload is the identity claims: the subject id, the name, the roles, the type, and the scope. The scope claim is a space-separated list of the held scopes. A verifier reads the public key at :pki:keys:{id} to check the signature. See wanderland-core-identity#claims for the full claim set, and wanderland-core-pki for the signing keys.

YamlStore

YamlStore is the implementation for development and for a test. It reads identities from a YAML file, and it issues tokens over the attenuation path. Wanderland::IDP.from_yaml(path, pki:) builds one.

Token Issuance

• Find the identity by its id.
• Keep the requested scopes the identity's roles allow, and reject the rest.
• Store the identity's key material at :pki:keys:{id}, with the scopes sign and verify.
• Sign the claims with the identity's private key, and return the token with the attenuated scopes.

Integration with PKI

The IDP signs a token through the identity's key at :pki:keys:{id}. It generates the key through wanderland-core-pki when the identity file carries none. The signature and the check are the PKI module's work, over the shared storage.

The Attenuation Model

Attenuation keeps a token inside an identity's authority. The roles are the ceiling — the most an identity may hold. The requested scopes are the request. The IDP keeps the scopes the roles allow, and the token carries only those.

• An identity with the roles read, write, and admin may request a token for read alone. The token scopes down.
• An identity may not request a scope its roles do not hold. The IDP raises ScopeExceedsRoleError, and it issues no token.

A token therefore never widens an identity's authority. It narrows the authority to the scopes one session needs.

The held scopes are the input to authorization. An authorization check reads the held scopes and compares them to what an operation requires. The operation runs when the held scopes cover the required scopes. The operation stops otherwise. So the token the IDP issues drives a capability check anywhere on the platform. See wanderland-core-authorization.

Source Files

• wanderland-core/lib/wanderland/idp.rb — the module and the from_yaml entry point.
• wanderland-core/lib/wanderland/idp/backend.rb — issue, validate_scopes, and mint_jwt.
• wanderland-core/lib/wanderland/idp/yaml_store.rb — the YAML-backed store.

Site Audit

wanderland.dev