mirror of
https://github.com/zitadel/zitadel.git
synced 2025-04-20 23:11:33 +00:00
0e812cf0f4
* docs: remove embedded content from rendered site * integrations applications * Apply suggestions from code review Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com> --------- Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
70 lines
3.9 KiB
Plaintext
70 lines
3.9 KiB
Plaintext
#### redirect_uri
|
|
|
|
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
|
The redirect_uri will be called after user authentication for code exchange.
|
|
|
|
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
|
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
|
|
|
## Auth Request
|
|
|
|
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
|
on /authorize with at least the following parameters:
|
|
|
|
- `client_id`: this tells the authorization server which application it is, copy from Console
|
|
- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
|
|
- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
|
|
- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
|
|
|
|
We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through
|
|
the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.
|
|
|
|
You don't need any additional parameter for this request. We're identifying the app by the `client_id` parameter.
|
|
|
|
Try out the request in our [OIDC Authentication Request Playground](/apis/openidoauth/authrequest?auth_method=Client%20Secret%20Basic).
|
|
|
|
### Additional parameters and customization
|
|
|
|
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
|
Please check the [authorization_endpoint reference](/apis/openidoauth/endpoints#authorization_endpoint) in the OAuth / OIDC documentation.
|
|
|
|
## Callback
|
|
|
|
Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
|
|
callback endpoint you provided by the `redirect_uri`.
|
|
|
|
:::note
|
|
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
|
|
the error will be display directly to the user on the auth server.
|
|
:::
|
|
|
|
Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
|
|
You will need this `code` in the token request.
|
|
|
|
If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
|
|
possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
|
|
Check the [error response section](/apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
|
|
|
|
## Token request
|
|
|
|
Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
|
|
|
|
- code: the code that was issued from the authorization request
|
|
- grant_type: must be `authorization_code`
|
|
- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
|
|
|
|
Depending on your authentication method you'll need additional headers and parameters:
|
|
|
|
Send your `client_id` and `client_secret` as Basic Auth Header. Note that OAuth2 requires client_id and client_secret to be form url encoded.
|
|
So check [Client Secret Basic Auth Method](/apis/openidoauth/authn-methods#client-secret-basic) on how to build it correctly.
|
|
|
|
```curl
|
|
curl --request POST \
|
|
--url {your-domain}/oauth/v2/token \
|
|
--header 'Authorization: Basic ${basic}' \
|
|
--header 'Content-Type: application/x-www-form-urlencoded' \
|
|
--data grant_type=authorization_code \
|
|
--data code=${code} \
|
|
--data redirect_uri=${redirect_uri}
|
|
```
|