Clients
Your tenant knows its people. Your app wants to know who they are. Between the two sits a rule: Odudu only talks to apps it has been told about. Telling it is called registering a client, and the registration is what lets a person trust the page that asked them to sign in.
In words: A public client, such as a browser or mobile app that holds no secret, and a confidential client, such as a server-side app that holds and proves a secret, both reach the tenant token endpoint. The endpoint checks the client id, the registered redirect address, the PKCE verifier and, for a confidential client, its secret.
What a client is
A client is one app, registered with one tenant. It has a client_id, a name, and a list of redirect addresses: the only places Odudu will send a person after they sign in. An address that is not on the list is refused, which stops somebody else's page from catching the result of a sign-in meant for yours.
Each client also has its own settings: how long its access tokens live, how long its refresh tokens live, which scopes it may ask for, and whether people must approve it on a consent screen.
Public and confidential
How an app can keep a secret decides the kind of client it is.
- A public client cannot keep a secret. A single-page app and a mobile app are public, because anyone can read the code that ships to the device. A public client holds no secret at all.
- A confidential client can keep one. A web app's server and a back-end service are confidential. It holds a credential, usually a client secret, and proves it when it calls the token endpoint.
You pick the kind when you register the client, and it decides which sign-in guide fits. A web app is confidential. A single-page app is public. A service with no person involved is confidential and uses the client_credentials grant.
PKCE protects the code in between
When a person signs in, Odudu sends the browser back with a short-lived code, and the app trades it for tokens. PKCE protects the code on the way. The app invents a secret for this one sign-in, sends only a fingerprint of it at the start, and shows the secret when it trades the code. Somebody who steals the code has the fingerprint, not the secret.
Every sign-in that uses a code uses PKCE, public or confidential, so there is nothing to switch on. A confidential client adds its own proof on top.
How a client proves who it is
A client shows who it is at the token endpoint. Its token_endpoint_auth_method says how.
| Method | What the client sends |
|---|---|
none | Nothing. PKCE protects the code. |
client_secret_basic | The secret in the HTTP Basic header. |
client_secret_post | The secret in the request body. |
private_key_jwt | A short-lived token signed with its private key. |
tls_client_auth | A TLS certificate, which a proxy passes on. |
A public client uses none. A confidential client uses any of the others.
tls_client_auth is listed only while ODUDU_TRUST_PROXY is on. client_secret_jwt is not supported.
With private_key_jwt the client signs a short-lived token with its private key, and Odudu stores no secret. In a standard install Odudu's own console client works this way. Call an API as a service shows how to set it up.
Service accounts and roles
A confidential client gets a service account, however it was created, including a tenant import. It is the identity the client uses when it signs in as itself with the client_credentials grant. A public client never has one, nor does the built-in admin client. A client cannot change between public and confidential. Switching the grant off keeps the account and its roles, but no token can be issued as it. Deleting the client deletes the account.
Include all roles in tokens is off by default: a token carries only the roles mapped to the granted scopes. Switched on, the client still has to ask for the roles scope. Scopes has the rule.
Who may register a client
An administrator registers clients from the console or the admin API, or seeds them from the command line. A tenant can also let apps register themselves. A client that registered itself with no token starts out with the consent screen switched on, because nobody vouched for it. A client an administrator registered does not ask for consent unless you turn it on. Consent and audit explains the screen.
Working with clients
- Decide whether the app can keep a secret. If it cannot, it is public.
- Register it with the redirect addresses it really uses, and no others.
- For a confidential client, store the secret where only the server can read it. The console shows a generated secret once, so copy it then.
- Choose the scopes it may ask for. Scopes explains how.
- Send people to the tenant's authorization address, then trade the code for tokens at the token endpoint,
POST /tenants/{tenant}/protocol/openid-connect/token.
If a client's secret leaks, issue a new one. Nothing else about the client has to change.
Where to go next
- Sign a user in registers a client and signs a person in end to end.
- Tokens explains what the client gets back.
- The client operations of the admin API list every setting.