Documentation
¶
Overview ¶
Package oauthtest checks an oauth.Provider against the contract the oauth plugin relies on, by driving it against a fake authorization server it starts. A provider written for one app, a preset, or an adapter over another OAuth library proves itself with one call rather than by finding out in production which rule it broke. The plugin's own Google, GitHub, OAuth2, OIDC and preset providers and contrib/goth all run it.
What a provider must do, case by case:
- build an authorization URL on the server's AuthorizePath carrying response_type=code, ClientID, RedirectURI, the state, the scopes WantScopes names and the S256 PKCE challenge it was given;
- exchange the code for the person's profile: the subject, the email, and the email verified flag exactly as the provider reported it (or never verified, with NeverVerified), plus the issued access token;
- turn every failure into an error: the token endpoint's error answer, a wrong PKCE verifier, a token answer that is not JSON or has no access token, a failing profile endpoint, and a profile without a subject.
It imports only the standard library, the core and plugin/oauth, so a provider's own tests can use it whatever else they depend on.
Index ¶
Constants ¶
const ( // AuthorizePath is the authorization endpoint. It answers a valid // request with a 302 to the redirect URI carrying a code, as a provider // does once the person has consented. AuthorizePath = "/authorize" // TokenPath is the token endpoint (authorization_code grant only). TokenPath = "/token" // UserInfoPath is the OpenID Connect userinfo endpoint: sub, email, // email_verified and name of the person behind the bearer token. UserInfoPath = "/userinfo" // JWKSPath publishes the key the ID tokens are signed with (ES256). JWKSPath = "/jwks" // DiscoveryPath is the OpenID Connect discovery document; the server // URL is the issuer. DiscoveryPath = "/.well-known/openid-configuration" )
The fake authorization server's endpoints, relative to the server URL a provider factory receives. The discovery document at DiscoveryPath names them too, so an OpenID Connect provider needs only the server URL as its issuer.
const ( // ClientID is the client id the server knows. ClientID = "oauthtest-client" // ClientSecret is that client's secret, checked at the token endpoint // in the form body or as HTTP Basic, unless PublicClient is given. ClientSecret = "oauthtest-secret" // RedirectURI is the redirect URI the kit passes to AuthCodeURL and // Exchange; a provider that sends another (goth's fixed callback URL) // is refused at the authorization endpoint. RedirectURI = "https://app.example/auth/oauth/callback" )
The credentials and redirect URI the provider under test must be built with. Fixed values rather than parameters, so the factory signature stays one argument and every provider is checked against the same expectations.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*config)
Option adjusts what Run expects of the provider.
func NeverVerified ¶
func NeverVerified() Option
NeverVerified declares that the provider reports every address as unverified, because its API says nothing about verification. The verified case then requires EmailVerified false; a provider must never claim more than its server said.
func NoPKCE ¶
func NoPKCE() Option
NoPKCE declares that the provider cannot send a PKCE challenge (an adapter over a library whose authorization URL takes none). The URL is then required to carry NO challenge, so the declaration cannot go stale silently, the wrong-verifier case is skipped, and Report.PKCE is false. The oauth plugin always generates a verifier; such a provider simply does not use it, and the flow rests on the state alone.
func PublicClient ¶
func PublicClient() Option
PublicClient makes the token endpoint expect the client id alone, with no secret, for a provider built with oauth.PublicClient.
func Route ¶
Route adds a GET profile endpoint at path that answers render(person) as JSON to the holder of an access token the server issued, for a provider whose profile API is not OpenID Connect userinfo (GitHub's /user and /user/emails, Discord's /users/@me). render must leave the subject out when Person.Subject is "", which is how the missing-subject case reaches the provider.
func WantScopes ¶
WantScopes makes the authorization URL carry every one of scopes in its space-separated scope parameter. Without it the scope is not checked, since some providers (Zoom) configure scopes on the app, not the URL.
type Person ¶
type Person struct {
// Subject is the server's stable id for the person; "" in the case
// that proves a profile without one is refused. Numeric, so a provider
// that parses its subject as a number (GitHub) can be checked.
Subject string
Email string
// EmailVerified is the server's claim that the person controls Email.
EmailVerified bool
Name string
}
Person is who signs in at the fake server in a case: what the provider reads back and must map onto oauth.Profile.
type Report ¶
type Report struct {
// Provider is the provider's Name.
Provider string
// PKCE says the authorization URL carried the S256 challenge and the
// token request the verifier. False only under NoPKCE.
PKCE bool
// ReportsVerified says the provider passed the server's email_verified
// claim through. False only under NeverVerified, where every address is
// treated as unverified.
ReportsVerified bool
// ProfileCall says the provider read the profile from an endpoint (the
// userinfo or a Route) rather than only from the ID token; the failing
// profile endpoint case runs only when it did.
ProfileCall bool
}
Report is what Run learned about the provider, for the test to assert or log. Run also logs it, so a provider's weaker guarantees (no PKCE) appear in the test output rather than only in its documentation.
func Run ¶
Run checks the provider that newProvider builds against a fake authorization server at the URL it is given. newProvider is called once per case, so a provider that caches (discovery) starts fresh; it must use ClientID, ClientSecret (unless PublicClient), RedirectURI as its redirect where it fixes one, and the server's endpoints (AuthorizePath, TokenPath, UserInfoPath, Route paths, or the URL itself as an OpenID Connect issuer).