Skip to content

Testing

Requires the oidc extra:

uv add "rn-forge-auth[oidc]"

rn_forge.auth.testing is not re-exported from rn_forge.auth — import it directly:

from rn_forge.auth.testing import FakeOidcProvider

rn_forge.auth.testing

An in-process OpenID Connect provider for tests.

:class:FakeOidcProvider serves discovery, a key set with rotation, an authorization endpoint, a token endpoint, UserInfo and back-channel logout tokens on a loopback port. Nothing leaves the machine. Each field of :class:Faults switches one failure on.

Requires the oidc extra. Not imported by :mod:rn_forge.auth; import this module directly.

Example: >>> with FakeOidcProvider() as idp: ... idp.issuer.startswith("http://127.0.0.1:") True

FakeOidcProvider(*, client_id='web-login', client_secret='fake-secret', redirect_uris=('http://127.0.0.1/callback',), user=None, tenant='tenant', id_token_ttl=300.0)

An OpenID Connect provider on 127.0.0.1 and an ephemeral port.

The issuer is http://127.0.0.1:<port>/<tenant>. The authorization endpoint approves user without a login page and redirects back with a single-use code; the token endpoint exchanges it, checking PKCE and the client's credentials. Use it as a context manager, or call :meth:start and :meth:close.

Parameters:

Name Type Description Default
client_id str

The registered client.

'web-login'
client_secret str | None

The client's secret, accepted as client_secret_post or HTTP Basic. None registers a public client.

'fake-secret'
redirect_uris Sequence[str]

The registered redirect URIs.

('http://127.0.0.1/callback',)
user Mapping[str, Any] | None

The claims of the user the authorization endpoint approves; it must contain sub.

None
tenant str

The issuer's path segment.

'tenant'
id_token_ttl float

Seconds an ID token or an access token stays valid.

300.0

Attributes:

Name Type Description
faults

The failure switches; assign :class:Faults or set fields.

deny_authorization

When true the authorization endpoint answers access_denied instead of approving.

oauth2_only

When true the provider behaves as a plain OAuth 2.0 server: the authorization endpoint accepts a request without the openid scope or a nonce, and the token response carries no ID token. The UserInfo endpoint then serves as the user endpoint.

advertise_end_session

Whether discovery lists end_session_endpoint.

auth_age

Seconds before each authorization request that the approved user is recorded as having authenticated; it sets the ID token's auth_time.

requests list[RecordedRequest]

Every request received, in order.

issuer

The issuer URL.

jwks_url

Where the key set is served.

forged_key cached property

A private key the key set never lists.

access_token(*, profile='rfc9068', audience='api://orders', subject=None, client_id=None, scope=None, ttl=300.0, **claims)

A signed JWT access token for bearer tests.

rfc9068 carries typ: at+jwt and iss, exp, aud, sub, client_id, iat and jti. rfc7519 carries no typ and only iss, exp, aud, sub and iat. Extra claims override those; a claim set to None is omitted.

close()

Stop serving and release the port.

fetches(suffix)

How many requests had a path ending with suffix.

logout_token(*, sid=None, sub=None, audience=None, ttl=120.0, **claims)

A back-channel logout token (OIDC Back-Channel Logout 1.0 §2.4).

Parameters:

Name Type Description Default
sid str | None

The session ID to end.

None
sub str | None

The subject whose sessions end.

None
audience str | None

The aud; defaults to the client.

None
ttl float

Seconds until exp.

120.0
**claims Any

Extra or overriding claims; None omits one.

{}

Raises:

Type Description
ValueError

Neither sid nor sub is given.

publish(kid, *, current=False)

Generate a key, list its public half in the key set under kid and return the private key. With current, new tokens are signed with it.

rotate_key(*, retire_old=False)

Publish a new key, make it the signing key and return its kid.

The old key stays in the key set unless retire_old is true.

sign(claims, *, typ=None, kid=None, alg='RS256', key=None)

A token with exactly claims (None values omitted).

Parameters:

Name Type Description Default
claims Mapping[str, Any]

The payload.

required
typ str | None

The typ header; None omits it.

None
kid str | None

The kid header; defaults to the current signing key's.

None
alg str

RS256, RS384, RS512 or none.

'RS256'
key RSAPrivateKey | None

The private key to sign with; defaults to the one published under kid.

None

start()

Begin serving. Calling it again has no effect.

Faults(response_iss=False, response_iss_missing=False, discovery_issuer=False, userinfo_sub_mismatch=False, userinfo_error=False, wrong_nonce=False, wrong_aud=False, wrong_azp=False, wrong_at_hash=False, expired=False, alg_none=False, unknown_kid=False) dataclass

Failure switches for :class:FakeOidcProvider. Each is off by default.

Attributes:

Name Type Description
response_iss bool

The authorization response carries an iss parameter naming another issuer.

response_iss_missing bool

The authorization response carries no iss parameter, although discovery advertises it.

discovery_issuer bool

The discovery document names another issuer.

userinfo_sub_mismatch bool

UserInfo returns a sub that differs from the ID token's.

userinfo_error bool

UserInfo answers 500.

wrong_nonce bool

The ID token carries a different nonce.

wrong_aud bool

The ID token's aud is another client.

wrong_azp bool

The ID token's aud lists the client and another one, and azp names the other one.

wrong_at_hash bool

The ID token's at_hash is not the access token's hash.

expired bool

The ID token's exp is in the past.

alg_none bool

The ID token is unsigned (alg: none).

unknown_kid bool

The ID token is signed with a key the key set does not list, under a kid it does not list.

RecordedRequest

Bases: NamedTuple

One request the provider received.

path instance-attribute

The URL path without the query string.