Skip to main content

OAuth Clients

Your own OAuth 2.0 apps at third-party providers (X, Google, GitHub, …), which actors connect through with OAuth connections.

Overview​

An OAuth client belongs to a project and holds what the provider issued you when you registered the app: its endpoints, client_id and a secret reference to its client secret. The app is yours: its name is the one on the provider's consent screen, and provider verifications (such as Google's restricted scopes) are yours to obtain.

See the Permissions Reference for the IAM action strings for this module.

Data Model​

FieldTypeDescription
idstringPublic identifier (e.g. oauc_…)
project_idstringID of the owning project
namestringLabel, such as the provider's name
authorize_urlstringThe provider's authorization endpoint; query parameters it already carries are kept
token_urlstringThe provider's token endpoint
revocation_urlstring | nullRFC 7009 revocation endpoint, called when a connection is deleted
client_idstringYour app's client ID
client_secretstring | null{{secret:sec_…}} reference to the client secret; null for a public client
scopesstring[]Scopes requested at authorization
pkcebooleanWhether authorization uses PKCE S256 (default true)
token_endpoint_auth_methodstringclient_secret_basic (default) or client_secret_post
redirect_uristring | nullThe callback registered with the provider; null is {SOAT_BASE_URL}/api/v1/oauth-connections/callback
authorize_paramsobject | nullExtra authorize URL parameters, such as Google's { "access_type": "offline", "prompt": "consent" } for a refresh token
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last-updated timestamp

Key Concepts​

The client secret is a reference​

client_secret takes only a secret reference; a literal is 400 VALIDATION_FAILED. Writing one needs secrets:UseSecret on the secret, else 403 FORBIDDEN. The reference is what GET returns.

Redirect URI​

Register redirect_uri with the provider. A client created without one, or written with null, stores the deployment's OAUTH_DEFAULT_REDIRECT_URI when it is set, over REST, a formation and a builtin action alike (Configuration). Unset, it stays null: this server's own callback, which needs SOAT_BASE_URL. A front end that receives the provider's redirect itself (its own domain on the consent screen) forwards code and state to GET /api/v1/oauth-connections/callback.

In a formation​

A template declares a client as an oauth_client resource with the fields of POST /api/v1/oauth-clients, authorized by the same actions. client_secret references a template secret with a sub, and a tool names the client with a ref, which also orders the client before the tool:

{
"resources": {
"XSecret": {
"type": "secret",
"properties": { "name": "x-client-secret", "value": "<client secret>" }
},
"XClient": {
"type": "oauth_client",
"properties": {
"name": "x",
"authorize_url": "https://x.com/i/oauth2/authorize",
"token_url": "https://api.x.com/2/oauth2/token",
"client_id": "Tm9ZWdEX2hQ",
"client_secret": { "sub": "{{secret:${XSecret}}}" },
"scopes": ["tweet.read", "users.read", "offline.access"]
}
},
"XProfile": {
"type": "tool",
"properties": {
"name": "x-profile",
"type": "http",
"execute": {
"url": "https://api.x.com/2/users/me",
"auth": {
"type": "oauth_connection",
"oauth_client_id": { "ref": "XClient" }
}
}
}
}
}
}

A literal client_secret fails validate-formation. Deleting the formation deletes the client and its connections.

Deletion​

Deleting a client deletes every connection made through it, without revoking them at the provider; delete the connections first to revoke.

Configuration​

VariableDefaultDescription
OAUTH_DEFAULT_REDIRECT_URI(unset)The redirect_uri a client written without one stores; an http(s) URL

Examples​

Create a client for X​

soat create-oauth-client --project-id proj_ABC --name x \
--authorize-url https://x.com/i/oauth2/authorize \
--token-url https://api.x.com/2/oauth2/token \
--revocation-url https://api.x.com/2/oauth2/revoke \
--client-id Tm9ZWdEX2hQ \
--client-secret '{{secret:sec_01}}' \
--scopes '["tweet.read","users.read","offline.access"]'