mirror of
https://github.com/zitadel/zitadel.git
synced 2024-12-04 23:45:07 +00:00
docs: Contribution guidelines (#7443)
* docs: gender neutrality * docs: gender neutrality * docs: gender neutrality * Update docs/docs/concepts/features/identity-brokering.md Co-authored-by: Tim Möhlmann <tim+github@zitadel.com> * Update docs/docs/guides/integrate/login-ui/mfa.mdx Co-authored-by: Tim Möhlmann <tim+github@zitadel.com> * Update docs/docs/guides/integrate/login-ui/passkey.mdx Co-authored-by: Tim Möhlmann <tim+github@zitadel.com> * Update internal/static/i18n/en.yaml Co-authored-by: Tim Möhlmann <tim+github@zitadel.com> * Update internal/static/i18n/en.yaml Co-authored-by: Tim Möhlmann <tim+github@zitadel.com> --------- Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>
This commit is contained in:
Fabi
GitHub
parent
2731099db3
commit
0542b29517
@ -108,13 +108,13 @@ Please make sure you cover your changes with tests before marking a Pull Request
|
||||
|
||||
The code consists of the following parts:
|
||||
|
||||
| name | description | language | where to find |
|
||||
| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------- |
|
||||
| backend | Service that serves the grpc(-web) and RESTful API | [go](https://go.dev) | [API implementation](./internal/api/grpc) |
|
||||
| console | Frontend the user interacts with after he is logged in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) |
|
||||
| name | description | language | where to find |
|
||||
| --------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------- |
|
||||
| backend | Service that serves the grpc(-web) and RESTful API | [go](https://go.dev) | [API implementation](./internal/api/grpc) |
|
||||
| console | Frontend the user interacts with after log in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) |
|
||||
| login | Server side rendered frontend the user interacts with during login | [go](https://go.dev), [go templates](https://pkg.go.dev/html/template) | [./internal/api/ui/login](./internal/api/ui/login) |
|
||||
| API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) |
|
||||
| docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./docs](./docs) |
|
||||
| API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) |
|
||||
| docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./docs](./docs) |
|
||||
|
||||
Please validate and test the code before you contribute.
|
||||
|
||||
@ -123,6 +123,24 @@ We add the label "good first issue" for problems we think are a good starting po
|
||||
- [Issues for first time contributors](https://github.com/zitadel/zitadel/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||
- [All issues](https://github.com/zitadel/zitadel/issues)
|
||||
|
||||
### General Guidelines
|
||||
|
||||
#### Gender Neutrality and Inclusive Language
|
||||
|
||||
We are committed to creating a welcoming and inclusive community for all developers, regardless of their gender identity or expression. To achieve this, we are actively working to ensure that our contribution guidelines are gender-neutral and use inclusive language.
|
||||
|
||||
**Use gender-neutral pronouns**:
|
||||
Don't use gender-specific pronouns unless the person you're referring to is actually that gender.
|
||||
In particular, don't use he, him, his, she, or her as gender-neutral pronouns, and don't use he/she or (s)he or other such punctuational approaches. Instead, use the singular they.
|
||||
|
||||
**Choose gender-neutral alternatives**:
|
||||
Opt for gender-neutral terms instead of gendered ones whenever possible.
|
||||
Replace "policeman" with "police officer," "manpower" with "workforce," and "businessman" with "entrepreneur" or "businessperson."
|
||||
|
||||
**Avoid ableist language**:
|
||||
Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others.
|
||||
Choose alternative words depending on the context.
|
||||
|
||||
### Backend/login
|
||||
|
||||
By executing the commands from this section, you run everything you need to develop the ZITADEL backend locally.
|
||||
|
||||
@ -11,7 +11,7 @@ This identity is known as federated identity and the pattern behind this is iden
|
||||
A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called an identity broker.
|
||||
Federated identity management is an arrangement that is made between two or more such identity brokers across organizations.
|
||||
|
||||
For example, if Google is configured as an identity provider in your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL. Because Google is registered as a trusted identity provider, the user will be able to login in with the Google account after the user is linked with an existing ZITADEL account (if he is already registered) or a new one with the claims provided by Google.
|
||||
For example, if Google is configured as an identity provider in your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL. Because Google is registered as a trusted identity provider, the user will be able to login in with the Google account after the user is linked with an existing ZITADEL account (if the user is already registered) or a new one with the claims provided by Google.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ Go to [Applications](./applications) for more details.
|
||||
To enable another organization to use a project, the organization needs a grant to the project.
|
||||
Only the selected roles will be available to the granted organization.
|
||||
|
||||
The granted organization will be able to manage the authorizations of his users for the granted project by himself in his own organization.
|
||||
The granted organization will be able to manage the authorizations of their users for the granted project by themselves in their organization.
|
||||
|
||||
More about granted projects: [Granted Projects](./granted_projects)
|
||||
|
||||
|
||||
@ -78,11 +78,11 @@ router.Handle("/auth/", z.Authentication)
|
||||
***Authentication checks***
|
||||
|
||||
To ensure the user is authenticated before they are able to use your application, the middleware provides two options:
|
||||
- You can either require the user to be authenticated. If he's not yet, he will be automatically redirected to the Login UI:
|
||||
- You can either require the user to be authenticated. If they haven't already, they will be automatically redirected to the Login UI:
|
||||
```go
|
||||
mw.RequireAuthentication()(handler)
|
||||
```
|
||||
- You can just check if he already is, but still continue serving the page:
|
||||
- You can just check the user's authentication status, but still continue serving the page:
|
||||
```go
|
||||
mw.CheckAuthentication()(handler)
|
||||
```
|
||||
|
||||
@ -24,7 +24,7 @@ For **GitHub Enterprise** go to your GitHub Enterprise home page and then to Set
|
||||
|
||||
Fill in the application name and homepage URL.
|
||||
|
||||
You have to add the authorization callback URL, where GitHub should redirect, after the user has authenticated himself.
|
||||
You have to add the authorization callback URL, where GitHub should redirect, after the user has authenticated themselves.
|
||||
In this example our test instance has the domain `https://acme-gzoe4x.zitadel.cloud`.
|
||||
This results in the following authorization callback URL:
|
||||
`https://acme-gzoe4x.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
|
||||
@ -26,7 +26,7 @@ For **GitLab Self-Hosted** go to your GitLab self-hosted instance and follow the
|
||||
|
||||
Fill in the application name.
|
||||
|
||||
You have to add the redirect URI, where GitLab should redirect, after the user has authenticated himself.
|
||||
You have to add the redirect URI, where GitLab should redirect, after the user has authenticated.
|
||||
In this example our test instance has the domain `https://acme-gzoe4x.zitadel.cloud`.
|
||||
This results in the following redirect URI:
|
||||
`https://acme-gzoe4x.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
Your user has successfully authenticated, and now you ask him if he wants to setup MFA to have a more secure account.
|
||||
When he starts the configuration, first you want him to show the possible methods.
|
||||
Your user has successfully authenticated, and now you ask them if they want to setup MFA to have a more secure account.
|
||||
When the user starts the configuration, first you want to show them the possible methods.
|
||||
You can either list it implicitly or call the settings service from ZITADEL to get what is configured on the login settings.
|
||||
|
||||
More detailed information about the API: [Get Login Settings Documentation](/apis/resources/settings_service/settings-service-get-login-settings)
|
||||
|
||||
@ -64,7 +64,7 @@ Response Example:
|
||||
|
||||
### Verify TOTP Registration
|
||||
|
||||
When the user has added the account to his authenticator app, he has to enter the code from the App to finish the registration.
|
||||
When the user has added the account to the authenticator app, the code from the App has to be entered to finish the registration.
|
||||
This code has to be sent to the verify endpoint in ZITADEL.
|
||||
|
||||
More detailed information about the API: [Verify TOTP Documentation](/apis/resources/user_service/user-service-verify-totp-registration)
|
||||
@ -128,7 +128,7 @@ Example Response
|
||||
|
||||
### Check TOTP
|
||||
|
||||
Now you can show the code field to the user, where he has to enter the code from the Authenticator App.
|
||||
Now you can show the code field to the user, where the code needs to be entered from the Authenticator App.
|
||||
With that code you have to update the existing session with a totp check.
|
||||
|
||||
More detailed information about the API: [Update session Documentation](/apis/resources/session_service/session-service-set-session)
|
||||
@ -258,7 +258,7 @@ curl --request POST \
|
||||
|
||||
### Check SMS Code
|
||||
|
||||
In the next step you should show the user a code field, where he can enter the code, he got as SMS.
|
||||
In the next step you should prompt the user to enter the SMS verification code in the provided field.
|
||||
The update session request has a check otpSMS where you should send the code, the user has entered.
|
||||
|
||||
Example Request
|
||||
@ -347,7 +347,7 @@ curl --request POST \
|
||||
|
||||
### Check Email Code
|
||||
|
||||
In the next step you should show the user a code field, where he can enter the code, he got per E-Mail.
|
||||
Next, display a code field for the user to enter the verification code they received via email.
|
||||
The update session request has a check otpEmail where you should send the code, the user has entered.
|
||||
|
||||
Example Request
|
||||
|
||||
@ -23,7 +23,7 @@ There are two options to onboard users with passkeys:
|
||||
|
||||
### Send Registration Link
|
||||
|
||||
When you want to send a link to your user, that enables him to register a new passkey device, you can choose if ZITADEL sends the code or ZITADEL can return the code in the API response. This way you can send a link through any channel of your choice (email, sms, phone, in-person, postal, ...).
|
||||
When you want to send a link to your user, that enables them to register a new passkey device, you can choose if ZITADEL sends the code or ZITADEL can return the code in the API response. This way you can send a link through any channel of your choice (email, sms, phone, in-person, postal, ...).
|
||||
|
||||
If you asked ZITADEL to send the link to the user please make sure to populate the link with the needed values that point towards your registration UI.
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ title: Password Reset/Change in a Custom Login UI
|
||||
sidebar_label: Password Reset/Change
|
||||
---
|
||||
|
||||
When your user is on the password screen and has forgotten his password you will probably want him to be able to reset by himself.
|
||||
When a user is on the password screen and has forgotten the password you will probably want them to be able to reset it by themselves.
|
||||
|
||||
## Flow
|
||||
|
||||
@ -12,7 +12,7 @@ When your user is on the password screen and has forgotten his password you will
|
||||
## Request Password Reset
|
||||
|
||||
First you will have to make a request, to ask for a password reset.
|
||||
The goal is to send the user a verification code, which he can use to verify the password reset request.
|
||||
The goal is to send the user a verification code, which can be entered to verify the password reset request.
|
||||
|
||||
There are two possible ways: You can either let ZITADEL send the notification with the verification code, or you can ask ZITADEL for returning the code and send the email by yourself.
|
||||
|
||||
|
||||
@ -86,7 +86,7 @@ The following requests can be useful for registration:
|
||||
|
||||
## Create Session with User Check
|
||||
|
||||
After you have created a new user, you can redirect him to your login screen.
|
||||
After you have created a new user, you can redirect them to your login screen.
|
||||
You can either create a new empty session as soon as the first login screen is shown or update it with each piece of information you get throughout the process.
|
||||
Or you can create a new session with the first credentials a user enters.
|
||||
In the following example, we assume that the login flow asks for the username in the first step, and in the second for the password.
|
||||
|
||||
@ -35,7 +35,7 @@ The following diagram demonstrates a basic authorization_code flow:
|
||||
|
||||
1. When an unauthenticated user visits your application,
|
||||
2. you will create an authorization request to the authorization endpoint.
|
||||
3. The Authorization Server (ZITADEL) will send an HTTP 302 to the user's browser, which will redirect him to the login UI.
|
||||
3. The Authorization Server (ZITADEL) will send an HTTP 302 to the user's browser, which will redirect them to the login UI.
|
||||
4. The user will have to authenticate using the demanded auth mechanics.
|
||||
5. Your application will be called on the registered callback path (redirect_uri) and be provided an authorization_code.
|
||||
6. This authorization_code must then be sent together with you applications authentication (client_id + client_secret) to the token_endpoint
|
||||
|
||||
@ -27,7 +27,7 @@ Roles can be requested via our auth and management APIs, from userinfo endpoint
|
||||
|
||||
### Generate a token
|
||||
|
||||
You must first of all generate a token for the user. If it’s a human user, he would be using a front-end application and logging in via the browser or device. An access token will be returned after they log in successfully. A machine user will use a script or other program to generate a token using the JWT profile or client credentials grant types.
|
||||
You must first of all generate a token for the user. For human users, the typical approach involves using a front-end application and logging in through the browser or device. An access token will be returned after they log in successfully. A machine user will use a script or other program to generate a token using the JWT profile or client credentials grant types.
|
||||
|
||||
How to generate a token:
|
||||
|
||||
|
||||
@ -16,7 +16,7 @@ For the moment all users with access to the Customer Portal will have the role "
|
||||
3. Fill in the Firstname, Lastname, Email and the username
|
||||
4. Click create
|
||||
|
||||
The user will get a verification email, by clicking the button in the mail, he will get to the user activation screen and has to enter a password.
|
||||
The user will receive a verification email. Clicking the button in the email will lead to the user activation screen where password creation is required.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -22,6 +22,6 @@ If no password is set initially, the initialization mail prompting the user to s
|
||||
|
||||
You can prompt the user to add a second factor method too by checking the **Force MFA** toggle in [Login behaviour settings](/docs/guides/manage/console/instance-settings#login-behavior-and-access).
|
||||
|
||||
When logged in, a user can then manage his profile in console himself, adding a profile picture, external IDPs and Passwordless authentication devices.
|
||||
When logged in, a user can then manage the profile in the console, adding a profile picture, external IDPs and Passwordless authentication devices.
|
||||
|
||||
<img src="/docs/img/guides/console/myprofile.png" alt="Profile Self Manage" />
|
||||
|
||||
@ -11,7 +11,7 @@ Date: Calendar week 41
|
||||
## Description
|
||||
|
||||
When users are redirected to the ZITADEL Login-UI without any organizational context, they're currently presented a login screen,
|
||||
based on the instance settings, e.g. available IDPs and possible login mechanisms. If the user will then register himself,
|
||||
based on the instance settings, e.g. available IDPs and possible login mechanisms. If the user will then register themselves,
|
||||
by the registration form or through an IDP, the user will always be created on the default organization.
|
||||
|
||||
This behavior led to confusion, e.g. when activating IDPs on default org would not show up in the Login-UI, because they would still be loaded from the instance settings.
|
||||
|
||||
@ -79,7 +79,7 @@ We understand that these advisories may include breaking changes, and we aim to
|
||||
<td>
|
||||
When users are redirected to the ZITADEL Login-UI without any organizational context,
|
||||
they're currently presented a login screen, based on the instance settings,
|
||||
e.g. available IDPs and possible login mechanisms. If the user will then register himself,
|
||||
e.g. available IDPs and possible login mechanisms. If the user will then register themselves,
|
||||
by the registration form or through an IDP, the user will always be created on the default organization.
|
||||
With the introduced change, the settings will no longer be loaded from the instance, but rather the default organization directly.
|
||||
</td>
|
||||
|
||||
@ -705,7 +705,7 @@ func TestServer_DeleteSession_own_session(t *testing.T) {
|
||||
})
|
||||
require.Error(t, err)
|
||||
|
||||
// delete the new (user1) session by himself
|
||||
// delete the new (user1) session by themselves
|
||||
_, err = Client.DeleteSession(Tester.WithAuthorizationToken(context.Background(), token1), &session.DeleteSessionRequest{
|
||||
SessionId: createResp.GetSessionId(),
|
||||
})
|
||||
|
||||
@ -214,7 +214,7 @@ func (c *Commands) PasswordCodeSent(ctx context.Context, orgID, userID string) (
|
||||
return err
|
||||
}
|
||||
|
||||
// PasswordChangeSent notification sent that user changed his password
|
||||
// PasswordChangeSent notification sent that user changed password
|
||||
func (c *Commands) PasswordChangeSent(ctx context.Context, orgID, userID string) (err error) {
|
||||
if userID == "" {
|
||||
return zerrors.ThrowInvalidArgument(nil, "COMMAND-pqlm2n", "Errors.User.UserIDMissing")
|
||||
|
||||
@ -570,7 +570,7 @@ EventTypes:
|
||||
removed: Target deleted
|
||||
user:
|
||||
added: User added
|
||||
selfregistered: User registered himself
|
||||
selfregistered: User registered themself
|
||||
initialization:
|
||||
code:
|
||||
added: Initialization code generated
|
||||
@ -609,7 +609,7 @@ EventTypes:
|
||||
failed: Secret check failed
|
||||
human:
|
||||
added: Person added
|
||||
selfregistered: Person registered himself
|
||||
selfregistered: Person registered themself
|
||||
avatar:
|
||||
added: Avatar added
|
||||
removed: Avatar removed
|
||||
|
||||
@ -4440,7 +4440,7 @@ message SetUpOrgRequest {
|
||||
string display_name = 4 [
|
||||
(validate.rules).string = {max_len: 200},
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "a user can set his display name if nothing is set ZITADEL computes \"first_name last_name\"";
|
||||
description: "a user can set the display name if nothing is set ZITADEL computes \"first_name last_name\"";
|
||||
max_length: 200;
|
||||
example: "\"Gigi Giraffe\"";
|
||||
}
|
||||
@ -6373,7 +6373,7 @@ message GetLoginPolicyResponse {
|
||||
message UpdateLoginPolicyRequest {
|
||||
bool allow_username_password = 1 [
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "defines if a user is allowed to log in with his username and password"
|
||||
description: "defines if a user is allowed to log in with username and password"
|
||||
}
|
||||
];
|
||||
bool allow_register = 2 [
|
||||
|
||||
@ -159,7 +159,7 @@ message LoginPolicy {
|
||||
zitadel.v1.ObjectDetails details = 1;
|
||||
bool allow_username_password = 2 [
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "defines if a user is allowed to log in with his username and password"
|
||||
description: "defines if a user is allowed to log in with username and password"
|
||||
}
|
||||
];
|
||||
bool allow_register = 3 [
|
||||
|
||||
@ -11,7 +11,7 @@ import "google/protobuf/duration.proto";
|
||||
message LoginSettings {
|
||||
bool allow_username_password = 1 [
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "defines if a user is allowed to log in with his username and password";
|
||||
description: "defines if a user is allowed to log in with username and password";
|
||||
}
|
||||
];
|
||||
bool allow_register = 2 [
|
||||
|
||||
@ -108,7 +108,7 @@ message Profile {
|
||||
];
|
||||
string display_name = 4 [
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "a user can set his display name, if nothing is set ZITADEL computes \"first_name last_name\""
|
||||
description: "a user can set the display name, if nothing is set ZITADEL computes \"first_name last_name\""
|
||||
example: "\"Gigi Giraffe\"";
|
||||
}
|
||||
];
|
||||
@ -140,7 +140,7 @@ message Email {
|
||||
];
|
||||
bool is_email_verified = 2 [
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "Is true if the user verified his email or if the email is managed outside ZITADEL"
|
||||
description: "Is true if the user verified the email or if the email is managed outside ZITADEL"
|
||||
}
|
||||
];
|
||||
}
|
||||
@ -154,7 +154,7 @@ message Phone {
|
||||
];
|
||||
bool is_phone_verified = 2 [
|
||||
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
||||
description: "Is true if the user verified his phone or if the phone is managed outside ZITADEL"
|
||||
description: "Is true if the user verified the phone or if the phone is managed outside ZITADEL"
|
||||
}
|
||||
];
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user