From 4ebbfa7326c7be7dad9528da30b1d10e3c4ae9eb Mon Sep 17 00:00:00 2001 From: peintnermax Date: Mon, 2 Sep 2024 11:25:08 +0200 Subject: [PATCH] update oidc-playground link --- docs/docs/apis/introduction.mdx | 11 ++- .../identity-providers/_test_setup.mdx | 8 +- .../guides/integrate/login/login-users.mdx | 2 +- .../login/oidc/authmethods/_basic.mdx | 2 +- .../login/oidc/authmethods/_jwtpk.mdx | 2 +- .../login/oidc/authmethods/_pkce.mdx | 2 +- .../guides/integrate/onboarding/end-users.mdx | 39 ++++++--- .../manage/console/default-settings.mdx | 2 +- .../guides/manage/console/organizations.mdx | 2 +- docs/docs/guides/manage/customize/branding.md | 10 +-- .../guides/manage/customize/user-metadata.md | 85 +++++++++---------- docs/docs/guides/migrate/introduction.md | 5 +- .../solution-scenarios/domain-discovery.mdx | 2 +- docs/src/components/authrequest.jsx | 2 +- 14 files changed, 93 insertions(+), 81 deletions(-) diff --git a/docs/docs/apis/introduction.mdx b/docs/docs/apis/introduction.mdx index 4facd30ea6..5ac010dda8 100644 --- a/docs/docs/apis/introduction.mdx +++ b/docs/docs/apis/introduction.mdx @@ -36,7 +36,7 @@ Accessing the ZITADEL APIs through a service user might require additional steps - Standard and reserved [scopes reference](/docs/apis/openidoauth/scopes) - Standard, custom, and reserved [claims reference](/docs/apis/openidoauth/claims) -The [OIDC Playground](/docs/apis/openidoauth/authrequest) is for testing OpenID authentication requests and their parameters. +The [OIDC Playground](/oidc-playground) is for testing OpenID authentication requests and their parameters. ### SAML 2.0 @@ -70,7 +70,7 @@ ZITADEL APIs were organized by UseCase/Context, such as Auth API for authenticat This led to confusion about which API to use, particularly for requests that could be useful across multiple APIs but with different filters. For instance, SearchUsers on an Instance Level or on an Organization Level. -To address this issue, ZITADEL is migrating to a [resource-based API](#zitadel-apis-resource-based). +To address this issue, ZITADEL is migrating to a [resource-based API](#zitadel-apis-resource-based). ::: @@ -224,7 +224,6 @@ Definition: - ## API definitions Each service's proto definition is located in the source control on GitHub. @@ -270,8 +269,8 @@ As you can see the `GetMyUser` function is also available as a REST service unde In the table below you can see the URI of those calls. -| Service | URI | -| :------ | :-------------------------------------------------- | +| Service | URI | +| :------ | :---------------------------------------------------- | | REST | $ZITADEL_DOMAIN/auth/v1/users/me | | GRPC | $ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/GetMyUser | @@ -281,7 +280,7 @@ ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or yo The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Console UI, which you'll find under `{your_domain}/ui/console/`. -Are you self-hosting and having troubles with *Instance not found* errors? [Check out this page](/docs/self-hosting/manage/custom-domain). +Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](/docs/self-hosting/manage/custom-domain). ## API path prefixes diff --git a/docs/docs/guides/integrate/identity-providers/_test_setup.mdx b/docs/docs/guides/integrate/identity-providers/_test_setup.mdx index 1cdbe73d39..9256ad0461 100644 --- a/docs/docs/guides/integrate/identity-providers/_test_setup.mdx +++ b/docs/docs/guides/integrate/identity-providers/_test_setup.mdx @@ -1,11 +1,11 @@

-To test the setup, use incognito mode and browse to your login page. -You see a new button which redirects you to {props.loginscreen} screen. + To test the setup, use incognito mode and browse to your login page. You see a + new button which redirects you to {props.loginscreen} screen.

By default, ZITADEL shows what you define in the default settings. If you overwrite the default settings for an organization, you need to send the organization scope in your auth request. -The organization scope looks like this: ```urn:zitadel:iam:org:id:{id}```. +The organization scope looks like this: `urn:zitadel:iam:org:id:{id}`. You can [read more about the reserved scopes](/apis/openidoauth/scopes#reserved-scopes) -or [use the ZITADEL OIDC Playground](/apis/openidoauth/authrequest) to see what happens with the login when you send different scopes. +or [use the ZITADEL OIDC Playground](/oidc-playground) to see what happens with the login when you send different scopes. diff --git a/docs/docs/guides/integrate/login/login-users.mdx b/docs/docs/guides/integrate/login/login-users.mdx index 82c9dbe5a4..406854aca7 100644 --- a/docs/docs/guides/integrate/login/login-users.mdx +++ b/docs/docs/guides/integrate/login/login-users.mdx @@ -20,7 +20,7 @@ In this guide, we will walk through the different protocols, features and concep OpenID Connect (OIDC) offers a modern and lightweight authentication protocol built on top of OAuth 2.0, providing flexible authentication flows and easy integration with web and mobile applications. ZITADEL offers a certified compliant implementation of the OpenID Connect Standard, ensuring compliance with proven security best practices. -Authenticating users through the OpenID Connect protocol typically requires an application to redirect the user with an [Auth Request](/docs/apis/openidoauth/authrequest) to the identity provider that contains information such as the requesting application, [scopes](/docs/apis/openidoauth/scopes), and redirect url. +Authenticating users through the OpenID Connect protocol typically requires an application to redirect the user with an [Auth Request](/docs/oidc-playground) to the identity provider that contains information such as the requesting application, [scopes](/docs/apis/openidoauth/scopes), and redirect url. The identity provider is not part of the original application, but a standalone service like ZITADEL that may run under the [same domain](/docs/concepts/features/custom-domain.md) The user will authenticate using their credentials. After successful authentication, the user will be redirected back to the original application. diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx index 5f4fbfbb5b..452efbe25f 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx @@ -21,7 +21,7 @@ the authentication process. The latter is used to bind the client session with t 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). +Try out the request in our [OIDC Authentication Request Playground](/oidc-playground?auth_method=Client%20Secret%20Basic). ### Additional parameters and customization diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx index 037df10d90..c957b5b514 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx @@ -23,7 +23,7 @@ You don't need any additional parameter for this request. We're identifying the So your request might look like this (linebreaks and whitespace for display reasons): -Try out the request in our [OIDC Authentication Request Playground](/apis/openidoauth/authrequest?auth_method=Client%20Secret%20Basic). +Try out the request in our [OIDC Authentication Request Playground](/oidc-playground?auth_method=Client%20Secret%20Basic). ### Additional parameters and customization diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx index 708eecc01a..d152bbf41e 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx @@ -29,7 +29,7 @@ the hash as well and to verify it's correct. In order to do so you're required t For example for `random-string` the code_challenge would be `9az09PjcfuENS7oDK7jUd2xAWRb-B3N7Sr3kDoWECOY` -Try out the request in our [OIDC Authentication Request Playground](/apis/openidoauth/authrequest). +Try out the request in our [OIDC Authentication Request Playground](/oidc-playground). ### Additional parameters and customization diff --git a/docs/docs/guides/integrate/onboarding/end-users.mdx b/docs/docs/guides/integrate/onboarding/end-users.mdx index 4c720be041..4064085bf9 100644 --- a/docs/docs/guides/integrate/onboarding/end-users.mdx +++ b/docs/docs/guides/integrate/onboarding/end-users.mdx @@ -4,6 +4,7 @@ sidebar_label: Onboard Users --- End Users have three different possibilities on how to login with ZITADEL. + 1. Local Account with Username, Password, MFA, Passkey, etc 2. Social Login like Google, Apple, Github, etc 3. External Identity Provider hosted/managed by Organization like Entra ID, LDAP, Okta etc @@ -12,9 +13,9 @@ You can either use the hosted login of ZITADEL to let users register themselves, ## Manually add/invite users -import CreateUser from '/docs/guides/manage/console/_create-user.mdx'; +import CreateUser from "/docs/guides/manage/console/_create-user.mdx"; - + ## Automated / Self-registration possibilities @@ -29,15 +30,15 @@ By default, redirecting from your application displays the login page. OpenID Connect (OIDC) allows you to control the initial screen by sending a [prompt](/docs/apis/openidoauth/endpoints#additional-parameters) parameter in the authorization request. With the `prompt=create`, the registration form/options will directly be shown to the user. -You can test the impact of the different prompts on your login UI in our [OIDC Playground](/docs/apis/openidoauth/authrequest). +You can test the impact of the different prompts on your login UI in our [OIDC Playground](/docs/oidc-playground). Per default a user will be registered to the default organization. By sending the scope below in your authorization request you can choose the organization to which the user will be added. + ``` urn:zitadel:iam:org:id:{id} ``` - Unfortunately, SAML doesn't offer the same level of control over the initial screen. You won't be able to directly influence which page (login or registration) is shown through the SAML flow. @@ -47,7 +48,10 @@ If an organization allows local user registration as well as registration with a As soon as users click the "register" button, they will be presented with a screen showing the different registration options. -Register Options +Register Options After that, the user can select either local user registration or an external provider. By pressing the button of an external provider, the user will directly be redirected to the provider for consent. @@ -62,14 +66,22 @@ If only one option is possible, the option will directly be selected and shown. To allow users to register themselves, you have to enable the "register allowed" in the login behavior settings. You will now see the register button on the login screen. -Register End User +Register End User If nothing else is specified, a user will be registered to the default organization. -Default Organization + +Default Organization You can specify another organization, by sending the organization scope in the authorization requests. By sending the scope below the settings of the specified organization will be triggered and only users of the said organization will be able to authenticate. The users will be registered to the given organization. + ``` urn:zitadel:iam:org:id:{id} ``` @@ -78,7 +90,10 @@ If the user chooses to register a local account, the register form will be shown All the mandatory fields like given name, family name, e-mail and password have to be filled. You can only setup authentication with the built-in form. -Register local user +Register local user #### Registration with Social Login @@ -91,7 +106,10 @@ Please follow the configuration guides for the needed providers: [Let Users Logi The configured providers will be shown on the first login screen or when the users click on the registration button, they will be able to choose between local account or the social login. -Register End User +Register End User #### Registration with Organization External Identity Provider @@ -110,6 +128,7 @@ ZITADEL allows you to build your own registration form and login UI. The registration process highly depends on your needs. We do have a guide series on how to build your own login ui, which also includes the registration of different authentication methods, such as: + - Password authentication - Multi-Factor - Passkeys @@ -127,4 +146,4 @@ We recommend storing business relevant data in the database of your application, #### Registration with Organization External Identity Provider If you want to know more about the multi-tenancy possibilities of ZITADEL, read the following blog post: -[Multi-Tenancy and Delegated Access Management with Organizations](https://zitadel.com/blog/multi-tenancy-with-organizations) \ No newline at end of file +[Multi-Tenancy and Delegated Access Management with Organizations](https://zitadel.com/blog/multi-tenancy-with-organizations) diff --git a/docs/docs/guides/manage/console/default-settings.mdx b/docs/docs/guides/manage/console/default-settings.mdx index 4936131029..1d47f143d4 100644 --- a/docs/docs/guides/manage/console/default-settings.mdx +++ b/docs/docs/guides/manage/console/default-settings.mdx @@ -148,7 +148,7 @@ The Login Policy defines how the login process should look like and which authen The Default Redirect URI will be used, if a user calls the login page directly. More specifically, typically a client will initiate login with an auth request. The auth request contains a client-id and a redirect uri, that must match the configuration in ZITADEL. -If there is no [auth request](https://zitadel.com/docs/apis/openidoauth/authrequest), users will be redirected to the Default Redirect URI, which is by default `https:///ui/console/` +If there is no [auth request](https://zitadel.com/docs/oidc-playground), users will be redirected to the Default Redirect URI, which is by default `https:///ui/console/` Reasons why ZITADEL doesn't have a redirect URI: diff --git a/docs/docs/guides/manage/console/organizations.mdx b/docs/docs/guides/manage/console/organizations.mdx index 924c02d045..6560a742d7 100644 --- a/docs/docs/guides/manage/console/organizations.mdx +++ b/docs/docs/guides/manage/console/organizations.mdx @@ -131,7 +131,7 @@ This means when you want to trigger the settings of an organization directly, ma urn:zitadel:iam:org:id:{id} ``` -Read more about the [scopes](/docs/apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Playground](/docs/apis/openidoauth/authrequest). +Read more about the [scopes](/docs/apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Playground](/docs/oidc-playground). ## Default organization diff --git a/docs/docs/guides/manage/customize/branding.md b/docs/docs/guides/manage/customize/branding.md index b6ffbf909d..14c18705f6 100644 --- a/docs/docs/guides/manage/customize/branding.md +++ b/docs/docs/guides/manage/customize/branding.md @@ -24,13 +24,13 @@ Upload your logo for the chosen theme, as soon as it is uploaded the preview on ### Colors -In the next part you can configure your colors. -Background colour is self-explanatory, the primary color will be used for buttons, links and some highlights. -The warn color is used for all the error messages and warnings and the font colour for texts. +In the next part you can configure your colors. +Background colour is self-explanatory, the primary color will be used for buttons, links and some highlights. +The warn color is used for all the error messages and warnings and the font colour for texts. ### Font -Last step to apply to your branding is the font upload. +Last step to apply to your branding is the font upload. The best way is to upload a ttf file after a successful upload you will see it in the font part, but not in the preview. ### Advanced Settings @@ -46,7 +46,7 @@ If you like to trigger your settings for your applications you have different po Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login/oidc/login-users#auth-request) to trigger your organization. The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login. -You can use our [OpenID Authentication Request Playground](/apis/openidoauth/authrequest) to learn more about how to trigger an [organization's policies and branding](/apis/openidoauth/authrequest#organization-policies-and-branding). +You can use our [OpenID Authentication Request Playground](/oidc-playground) to learn more about how to trigger an [organization's policies and branding](/oidc-playground#organization-policies-and-branding). ### 2. Setting on your Project diff --git a/docs/docs/guides/manage/customize/user-metadata.md b/docs/docs/guides/manage/customize/user-metadata.md index 0738b7f0c9..2ad4d60823 100644 --- a/docs/docs/guides/manage/customize/user-metadata.md +++ b/docs/docs/guides/manage/customize/user-metadata.md @@ -24,7 +24,7 @@ You can do so by using [Console](../console/users) or [setting user metadata](/d Most of the methods below require you to login with the correct user while setting some scopes. Make sure you pick the right user when logging into the test application. -Use the [OIDC authentication request playground](/docs/apis/openidoauth/authrequest) or the configuration of an [example client](/docs/sdk-examples/introduction) to set the required scopes and receive a valid access token. +Use the [OIDC authentication request playground](/docs/oidc-playground) or the configuration of an [example client](/docs/sdk-examples/introduction) to set the required scopes and receive a valid access token. :::info Getting a token In case you want to test out different settings configure an application with code flow (PKCE). @@ -54,27 +54,27 @@ curl --request GET \ --header "Authorization: Bearer $ACCESS_TOKEN" ``` -Replace `$ACCESS_TOKEN` with your user's access token. +Replace `$ACCESS_TOKEN` with your user's access token. The response will look something like this ```json { - "email":"road.runner@zitadel.com", - "email_verified":true, - "family_name":"Runner", - "given_name":"Road", - "locale":"en", - "name":"Road Runner", - "preferred_username":"road.runner@...asd.zitadel.cloud", - "sub":"166.....729", - "updated_at":1655467738, - //highlight-start - "urn:zitadel:iam:user:metadata":{ - "ContractNumber":"MTIzNA", - } - //highlight-end - } + "email": "road.runner@zitadel.com", + "email_verified": true, + "family_name": "Runner", + "given_name": "Road", + "locale": "en", + "name": "Road Runner", + "preferred_username": "road.runner@...asd.zitadel.cloud", + "sub": "166.....729", + "updated_at": 1655467738, + //highlight-start + "urn:zitadel:iam:user:metadata": { + "ContractNumber": "MTIzNA" + } + //highlight-end +} ``` You can grab the metadata from the reserved claim `"urn:zitadel:iam:user:metadata"` as key-value pairs. @@ -95,10 +95,10 @@ The result will give you something like: ```json { - "access_token":"jZuRixKQTVecEjKqw...kc3G4", - "token_type":"Bearer", - "expires_in":43199, - "id_token":"ey...Ww" + "access_token": "jZuRixKQTVecEjKqw...kc3G4", + "token_type": "Bearer", + "expires_in": 43199, + "id_token": "ey...Ww" } ``` @@ -106,12 +106,7 @@ When you decode the value of `id_token`, then the response will include the meta ```json { - "amr": [ - "password", - "pwd", - "mfa", - "otp" - ], + "amr": ["password", "pwd", "mfa", "otp"], "at_hash": "lGIblkTr8faHz2zd0oTddA", "aud": [ "170086824411201793@portal", @@ -157,7 +152,7 @@ You can use the authentication service to request and search for the user's meta The introspection endpoint and the token endpoint in the examples above do not require a special scope to access. Yet when accessing the authentication service, you need to pass the [reserved scope](/docs/apis/openidoauth/scopes#reserved-scopes) `urn:zitadel:iam:org:project:id:zitadel:aud` along with the authentication request. This scope allows the user to access ZITADEL's APIs, specifically the authentication API that we need for this method. -Use the [OIDC authentication request playground](/docs/apis/openidoauth/authrequest) or the configuration of an [example client](/docs/sdk-examples/introduction) to set the required scopes and receive a valid access token. +Use the [OIDC authentication request playground](/docs/oidc-playground) or the configuration of an [example client](/docs/sdk-examples/introduction) to set the required scopes and receive a valid access token. :::note Invalid audience If you get the error "invalid audience (APP-Zxfako)", then you need to add the reserved scope `urn:zitadel:iam:org:project:id:zitadel:aud` to your authentication request. @@ -199,23 +194,23 @@ An example response for your search looks like this: ```json { - "details":{ - "totalResult":"1", - "processedSequence":"2935", - "viewTimestamp":"2023-06-21T16:01:52.829838Z" - }, - "result":[ - { - "details":{ - "sequence":"409", - "creationDate":"2022-08-04T09:09:06.259324Z", - "changeDate":"2022-08-04T09:09:06.259324Z", - "resourceOwner":"170086363054473473" - }, - "key":"ContractNumber", - "value":"MTIzNA" - } - ] + "details": { + "totalResult": "1", + "processedSequence": "2935", + "viewTimestamp": "2023-06-21T16:01:52.829838Z" + }, + "result": [ + { + "details": { + "sequence": "409", + "creationDate": "2022-08-04T09:09:06.259324Z", + "changeDate": "2022-08-04T09:09:06.259324Z", + "resourceOwner": "170086363054473473" + }, + "key": "ContractNumber", + "value": "MTIzNA" + } + ] } ``` diff --git a/docs/docs/guides/migrate/introduction.md b/docs/docs/guides/migrate/introduction.md index 2955f91d4f..7c2eaebd88 100644 --- a/docs/docs/guides/migrate/introduction.md +++ b/docs/docs/guides/migrate/introduction.md @@ -16,8 +16,7 @@ Multi-tenancy in ZITADEL can be achieved through either [Instances](/docs/concep Where instances represent isolated ZITADEL instances, Organizations provide a more permeable approach to multi-tenancy. In most cases, when you want to achieve multi-tenancy, you use Organizations. Each organization can have their own set of Settings (eg, Security Policies, IDPs, Branding), Managers, and Users. -Please also consult our guide on [Solution Scenarios](/docs/guides/solution-scenarios/introduction -) for B2C and B2B for more details. +Please also consult our guide on [Solution Scenarios](/docs/guides/solution-scenarios/introduction) for B2C and B2B for more details. ## Delegated access management @@ -76,7 +75,7 @@ In case all your applications depend on ZITADEL after the migration date, and ZI For all other cases, we recommend that the **legacy system orchestrates the migration** of users to ZITADEL for more flexibility: - Update your legacy system to create a user in ZITADEL on their next login, if not already flagged as migrated, by using our APIs (you can set the password and a verified email) -- Redirect migrated users with a login hint in the [auth request](/docs/apis/openidoauth/authrequest.mdx) to ZITADEL to pre-select the user +- Redirect migrated users with a login hint in the [auth request](/docs/oidc-playground) to ZITADEL to pre-select the user In this case the migration can also be done as an import job or also allowing to create user session in both the legacy auth solution and ZITADEL in parallel with identity brokering: diff --git a/docs/docs/guides/solution-scenarios/domain-discovery.mdx b/docs/docs/guides/solution-scenarios/domain-discovery.mdx index e03c42bde4..cc0324ffef 100644 --- a/docs/docs/guides/solution-scenarios/domain-discovery.mdx +++ b/docs/docs/guides/solution-scenarios/domain-discovery.mdx @@ -31,7 +31,7 @@ When opening `login.mycompany.com` then the login policy of the instance will be This means that you have to configure the [Login and Access](/docs/guides/manage/console/default-settings#login-behavior-and-access) Policy and [Identity Providers](/docs/guides/manage/console/default-settings#identity-providers) for the **CIAM** users on the instance itself. :::info -You can also configure these settings on the default organization (see below) and send the scope `urn:zitadel:iam:org:id:{id}` with every [auth request](/docs/apis/openidoauth/authrequest#organization-policies-and-branding). +You can also configure these settings on the default organization (see below) and send the scope `urn:zitadel:iam:org:id:{id}` with every [auth request](/docs/oidc-playground#organization-policies-and-branding). ::: ### Default Organization diff --git a/docs/src/components/authrequest.jsx b/docs/src/components/authrequest.jsx index 71fd1349ea..5378c7581e 100644 --- a/docs/src/components/authrequest.jsx +++ b/docs/src/components/authrequest.jsx @@ -25,7 +25,7 @@ const LinkButton = ({ return (