Redirect URIs and client metadata
All domains, identifiers, and credentials in these examples are fictional.
A client registration holds two kinds of information that people rarely think about together. Some of it controls where the authorization server will send things, such as the addresses that may receive an authorization code. Some of it describes the client to the people asked to approve it, such as its name and logo. Both come from the client's developer, and both need care, because the first decides where credentials travel and the second shapes what people believe they are approving.
Registering return addresses
The Redirects and authorization codes lesson explained why the authorization server compares a requested redirect URI with the registered value exactly. Registration is where those values come from.
A client can register more than one. The printer's website might accept returns at two paths, one for connecting a photo account and one for adding a second account later:
https://printer.example/oauth/callback
https://printer.example/oauth/add-account/callbackEach authorization request names the one it wants, and the server accepts only an exact match with an entry in the list. Registering a pattern such as https://*.printer.example/ instead would let any address on any subdomain receive codes, including a forgotten marketing page or a subdomain someone else later controls. A list of specific addresses keeps the set of possible destinations small and known.
Web clients register HTTPS addresses on domains they control. The printer's test website, at https://test.printer.example/oauth/callback, belongs in the test client's registration, not in the production list. If it were added to the production client, a mistake on the test site could leak codes for real accounts.
Return addresses for installed apps
The printer's phone app has no website of its own to return to. It still needs the browser to hand the authorization response back to the app, and installed applications have three common ways to receive it.
A claimed HTTPS address is a web address that the operating system has verified belongs to the app, such as https://app.printer.example/oauth/callback. When the browser opens it, the system passes it to the app. Because the printing company had to prove control of the domain, another app cannot claim the same address. This is the strongest of the three where the platform supports it.
A private-use URI scheme is a custom scheme the app registers with the operating system, written as a reversed domain name the developer controls, such as example.printer:/oauth/callback. It is widely supported, but nothing stops another app on the same device from registering the same scheme. That is one reason installed apps must use PKCE: a code delivered to the wrong app is useless without the verifier.
A loopback address suits desktop applications and command-line tools. The application listens briefly on the local machine and registers an address such as http://127.0.0.1/oauth/callback. The operating system chooses a free port each time, so the authorization server lets the port vary for loopback addresses while still matching the rest exactly. Plain HTTP is acceptable here because the response never leaves the machine.
Describing the client
Registrations also hold client metadata: descriptive values the authorization server can show to people. Expressed with the standard field names that registration APIs use, the printer's might be:
{
"client_name": "Photo Printer",
"client_uri": "https://printer.example",
"logo_uri": "https://printer.example/logo.png",
"policy_uri": "https://printer.example/privacy",
"tos_uri": "https://printer.example/terms",
"contacts": ["[email protected]"]
}The consent screen uses these values. When you were asked whether to let the printer read your photos, the name, logo, and links on that screen came from this record. They help you recognize the application and find its privacy policy before you decide.
They are also exactly what an impostor would like to control. Anyone who can register a client can type "Photo Printer" into the name field and upload a familiar logo. The authorization server cannot simply trust what a developer wrote about their own application.
Careful services treat descriptive metadata as a claim. They may verify that the client controls the domain in client_uri, check that links point to the same site, review applications before they can reach many users, or show unverified clients with a clear warning. Where a consent screen shows the domain your browser will return to, that domain is often a better clue than the name. The name is free text. The return address is enforced.
Settings that limit requests
Alongside the description, a registration holds technical settings that narrow what the client may do. The most common, again with their standard names:
{
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "client_secret_basic",
"scope": "photos.read"
}Each one closes off requests the client has no reason to make. A client registered only for the authorization code flow cannot use client credentials. A client limited to photos.read cannot ask for photos.delete, however its request is written. A client registered for one authentication method cannot switch to another at the token endpoint. The next lesson looks at those methods.
These limits work best when they are as narrow as the client actually needs. A registration that allows every grant and every scope gives an attacker who obtains the client's credentials, or who controls one of its return addresses, every capability at once. A registration that matches the client's real behavior turns many mistakes and attacks into ordinary rejections.