mirror of
https://github.com/zitadel/zitadel.git
synced 2025-05-08 01:56:48 +00:00
ab7651fe26
* docs: identity provider and customer portal page * docs: identity provider and customer portal page * docs: identity provider and customer portal page * docs: urls
79 lines
4.0 KiB
Plaintext
79 lines
4.0 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.
|
|
|
|
So your request might look like this (linebreaks and whitespace for display reasons):
|
|
|
|
```curl
|
|
curl --request GET \
|
|
--url '{your-domain}/oauth/v2/authorize
|
|
?client_id=${client_id}
|
|
&redirect_uri=${redirect_uri}
|
|
&response_type=code
|
|
&scope=openid%20email%20profile'
|
|
```
|
|
|
|
### 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](/docs/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](/docs/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](/docs/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}
|
|
```
|