zitadel/proto/zitadel/idp.proto

syntax = "proto3";

import "zitadel/object.proto";
import "validate/validate.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "google/protobuf/duration.proto";

package zitadel.idp.v1;

option go_package ="github.com/zitadel/zitadel/pkg/grpc/idp";

message IDP {
    string id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"69629023906488334\"";
        }
    ];
    zitadel.v1.ObjectDetails details = 2;
    IDPState state = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "the state of the identity provider";
        }
    ];
    string name = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"google\"";
        }
    ];
    IDPStylingType styling_type = 5 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "some identity providers specify the styling of the button to their login";
        }
    ];
    IDPOwnerType owner = 6 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "the administrator of this identity provider";
        }
    ];
    oneof config {
        OIDCConfig oidc_config = 7;
        JWTConfig jwt_config = 9;
    }
    bool auto_register = 8;
}

message IDPUserLink {
    string user_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"69629023906488334\"";
            description: "the id of the user"
        }
    ];
    string idp_id = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"69629023906488334\"";
            description: "the id of the identity provider";
        }
    ];
    string idp_name = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"google\"";
            description: "the name of the identity provider";
        }
    ];
    string provided_user_id = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"as-12-df-89\"";
            description: "the id of the user provided by the identity provider";
        }
    ];
    string provided_user_name = 5 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"gigi.long-neck@gmail.com\"";
            description: "the id of the identity provider";
        }
    ];
    IDPType idp_type = 6 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "the authorization framework of the identity provider";
        }
    ];
}

message IDPLoginPolicyLink {
    string idp_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"69629023906488334\"";
            description: "the id of the identity provider"
        }
    ];
    string idp_name = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"google\"";
            description: "the name of the identity provider"
        }
    ];
    IDPType idp_type = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"IDP_TYPE_OIDC\"]"
            description: "the authorization framework of the identity provider";
        }
    ];
}

enum IDPState {
    IDP_STATE_UNSPECIFIED = 0;
    IDP_STATE_ACTIVE = 1;
    IDP_STATE_INACTIVE = 2;
}

enum IDPStylingType {
    STYLING_TYPE_UNSPECIFIED = 0;
    STYLING_TYPE_GOOGLE = 1;
}

// authorization framework of the identity provider
enum IDPType {
    IDP_TYPE_UNSPECIFIED = 0;
    IDP_TYPE_OIDC = 1;
    IDP_TYPE_JWT = 3;
}

// the owner of the identity provider.
enum IDPOwnerType {
    IDP_OWNER_TYPE_UNSPECIFIED = 0;
    // system is managed by the ZITADEL administrators
    IDP_OWNER_TYPE_SYSTEM = 1;
    // org is managed by de organization administrators
    IDP_OWNER_TYPE_ORG = 2;
}

message OIDCConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "client id generated by the identity provider";
        }
    ];
    string issuer = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://accounts.google.com\"";
            description: "the OIDC issuer of the identity provider";
        }
    ];
    repeated string scopes = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request on the identity provider";
        }
    ];
    OIDCMappingField display_name_mapping = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "definition which field is mapped to the display name of the user";
        }
    ];
    OIDCMappingField username_mapping = 5 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "definition which field is mapped to the email of the user";
        }
    ];
}

enum OIDCMappingField {
    OIDC_MAPPING_FIELD_UNSPECIFIED = 0;
    OIDC_MAPPING_FIELD_PREFERRED_USERNAME = 1;
    OIDC_MAPPING_FIELD_EMAIL = 2;
}


message JWTConfig {
    string jwt_endpoint = 1 [
        (validate.rules).string = {min_len: 1, max_len: 200},
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://accounts.google.com\"";
            description: "the endpoint where the JWT can be extracted";
        }
    ];
    string issuer = 2 [
        (validate.rules).string = {min_len: 1, max_len: 200},
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://accounts.google.com\"";
            description: "the issuer of the JWT (for validation)";
        }
    ];
    string keys_endpoint = 3 [
        (validate.rules).string = {min_len: 1, max_len: 200},
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://accounts.google.com/keys\"";
            description: "the endpoint to the key (JWK) which is used to sign the JWT with";
        }
    ];
    string header_name = 4 [
        (validate.rules).string = {min_len: 1, max_len: 200},
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"x-auth-token\"";
            description: "the name of the header where the JWT is sent in, default is authorization";
        }
    ];
}

message IDPIDQuery {
    string id = 1 [
        (validate.rules).string = {max_len: 200},
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"69629023906488334\"";
        }
    ];
}

message IDPNameQuery {
    string name = 1 [
        (validate.rules).string = {max_len: 200},
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"google\"";
        }
    ];
    zitadel.v1.TextQueryMethod method = 2 [
        (validate.rules).enum.defined_only = true,
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "defines which text equality method is used";
        }
    ];
}

message IDPOwnerTypeQuery {
    IDPOwnerType owner_type = 1 [
        (validate.rules).enum.defined_only = true,
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "search for custom or global identity providers";
        }
    ];
}

enum IDPFieldName {
    IDP_FIELD_NAME_UNSPECIFIED = 0;
    IDP_FIELD_NAME_NAME = 1;
}

message Provider {
    string id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"69629023906488334\"";
        }
    ];
    zitadel.v1.ObjectDetails details = 2;
    IDPState state = 3;
    string name = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"Google\"";
        }
    ];
    IDPOwnerType owner = 5;
    ProviderType type = 6;
    ProviderConfig config = 7;
}

enum ProviderType {
    PROVIDER_TYPE_UNSPECIFIED = 0;
    PROVIDER_TYPE_OIDC = 1;
    PROVIDER_TYPE_JWT = 2;
    PROVIDER_TYPE_LDAP = 3;
    PROVIDER_TYPE_OAUTH = 4;
    PROVIDER_TYPE_AZURE_AD = 5;
    PROVIDER_TYPE_GITHUB = 6;
    PROVIDER_TYPE_GITHUB_ES = 7;
    PROVIDER_TYPE_GITLAB = 8;
    PROVIDER_TYPE_GITLAB_SELF_HOSTED = 9;
    PROVIDER_TYPE_GOOGLE = 10;
    PROVIDER_TYPE_APPLE = 11;
    PROVIDER_TYPE_SAML = 12;
}

enum SAMLBinding {
    SAML_BINDING_UNSPECIFIED = 0;
    SAML_BINDING_POST = 1;
    SAML_BINDING_REDIRECT = 2;
    SAML_BINDING_ARTIFACT = 3;
}

enum SAMLNameIDFormat {
    SAML_NAME_ID_FORMAT_UNSPECIFIED = 0;
    SAML_NAME_ID_FORMAT_EMAIL_ADDRESS = 1;
    SAML_NAME_ID_FORMAT_PERSISTENT = 2;
    SAML_NAME_ID_FORMAT_TRANSIENT = 3;
}

message ProviderConfig {
    Options options = 1;
    oneof config {
        LDAPConfig ldap = 2;
        GoogleConfig google = 3;
        OAuthConfig oauth = 4;
        GenericOIDCConfig oidc = 5;
        JWTConfig jwt = 6;
        GitHubConfig github = 7;
        GitHubEnterpriseServerConfig github_es = 8;
        GitLabConfig gitlab = 9;
        GitLabSelfHostedConfig gitlab_self_hosted = 10;
        AzureADConfig azure_ad = 11;
        AppleConfig apple = 12;
        SAMLConfig saml = 13;
    }
}

message OAuthConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "client id generated by the identity provider";
        }
    ];
    string authorization_endpoint = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://accounts.google.com/o/oauth2/v2/auth\"";
            description: "the endpoint where ZITADEL send the user to authenticate";
        }
    ];
    string token_endpoint = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://oauth2.googleapis.com/token\"";
            description: "the endpoint where ZITADEL can get the token";
        }
    ];
    string user_endpoint = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://openidconnect.googleapis.com/v1/userinfo\"";
            description: "the endpoint where ZITADEL can get the user information";
        }
    ];
    repeated string scopes = 5 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request on the identity provider";
        }
    ];
    string id_attribute = 6 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"user_id\"";
            description: "defines how the attribute is called where ZITADEL can get the id of the user";
        }
    ];
}

message GenericOIDCConfig {
    string issuer = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"https://accounts.google.com/\"";
            description: "the OIDC issuer of the identity provider";
        }
    ];
    string client_id = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "client id generated by the identity provider";
        }
    ];
    repeated string scopes = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request on the identity provider";
        }
    ];
    bool is_id_token_mapping = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "true";
            description: "if true, provider information get mapped from the id token, not from the userinfo endpoint";
        }
    ];
}

message GitHubConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "the client ID of the GitHub App";
        }
    ];
    repeated string scopes = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request to GitHub";
        }
    ];
}

message GitHubEnterpriseServerConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "the client ID of the GitHub App";
        }
    ];
    string authorization_endpoint = 2;
    string token_endpoint = 3;
    string user_endpoint = 4;
    repeated string scopes = 5 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request to GitHub";
        }
    ];
}

message GoogleConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "client id of the Google application";
        }
    ];
    repeated string scopes = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request to Google";
        }
    ];
}

message GitLabConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "client id of the GitLab application";
        }
    ];
    repeated string scopes = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request to GitLab";
        }
    ];
}

message GitLabSelfHostedConfig {
    string issuer = 1;
    string client_id = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "client id of the GitLab application";
        }
    ];
    repeated string scopes = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request to GitLab";
        }
    ];
}

message LDAPConfig {
    repeated string servers = 1;
    bool start_tls = 2;
    string base_dn = 3;
    string bind_dn = 4;
    string user_base = 5;
    repeated string user_object_classes = 6;
    repeated string user_filters = 7;
    google.protobuf.Duration timeout = 8;
    LDAPAttributes attributes = 9;
}

message SAMLConfig {
    // Metadata of the SAML identity provider.
    bytes metadata_xml = 1;
    // Binding which defines the type of communication with the identity provider.
    zitadel.idp.v1.SAMLBinding binding = 2;
    // Boolean which defines if the authentication requests are signed.
    bool with_signed_request = 3;
    // `nameid-format` for the SAML Request.
    zitadel.idp.v1.SAMLNameIDFormat name_id_format = 4;
    // Optional name of the attribute, which will be used to map the user
    // in case the nameid-format returned is `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`.
    optional string transient_mapping_attribute_name = 5;
}

message AzureADConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"client-id\"";
            description: "client id of the Azure AD application";
        }
    ];
    AzureADTenant tenant = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Defines what user accounts should be able to login (Personal, Organizational, All)";
        }
    ];
    bool email_verified = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Azure AD doesn't send if the email has been verified. Enable this if the user email should always be added verified in ZITADEL (no verification emails will be sent)";
        }
    ];
    repeated string scopes = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"openid\", \"profile\", \"email\", \"User.Read\"]";
            description: "the scopes requested by ZITADEL during the request to Azure AD";
        }
    ];
}

message Options {
    bool is_linking_allowed = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Enable if users should be able to link an existing ZITADEL user with an external account.";
        }
    ];
    bool is_creation_allowed = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Enable if users should be able to create a new account in ZITADEL when using an external account.";
        }
    ];
    bool is_auto_creation = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Enable if a new account in ZITADEL should be created automatically when login with an external account.";
        }
    ];
    bool is_auto_update = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Enable if a the ZITADEL account fields should be updated automatically on each login.";
        }
    ];
    AutoLinkingOption auto_linking = 5 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            description: "Enable if users should get prompted to link an existing ZITADEL user to an external account if the selected attribute matches.";
        }
    ];
}

enum AutoLinkingOption {
    // AUTO_LINKING_OPTION_UNSPECIFIED disables the auto linking prompt.
    AUTO_LINKING_OPTION_UNSPECIFIED = 0;
    // AUTO_LINKING_OPTION_USERNAME will use the username of the external user to check for a corresponding ZITADEL user.
    AUTO_LINKING_OPTION_USERNAME = 1;
    // AUTO_LINKING_OPTION_EMAIL  will use the email of the external user to check for a corresponding ZITADEL user with the same verified email
    // Note that in case multiple users match, no prompt will be shown.
    AUTO_LINKING_OPTION_EMAIL = 2;
}

message LDAPAttributes {
    string id_attribute = 1 [(validate.rules).string = {max_len: 200}];
    string first_name_attribute = 2 [(validate.rules).string = {max_len: 200}];
    string last_name_attribute = 3 [(validate.rules).string = {max_len: 200}];
    string display_name_attribute = 4 [(validate.rules).string = {max_len: 200}];
    string nick_name_attribute = 5 [(validate.rules).string = {max_len: 200}];
    string preferred_username_attribute = 6 [(validate.rules).string = {max_len: 200}];
    string email_attribute = 7 [(validate.rules).string = {max_len: 200}];
    string email_verified_attribute = 8 [(validate.rules).string = {max_len: 200}];
    string phone_attribute = 9 [(validate.rules).string = {max_len: 200}];
    string phone_verified_attribute = 10 [(validate.rules).string = {max_len: 200}];
    string preferred_language_attribute = 11 [(validate.rules).string = {max_len: 200}];
    string avatar_url_attribute = 12 [(validate.rules).string = {max_len: 200}];
    string profile_attribute = 13 [(validate.rules).string = {max_len: 200}];
}

enum AzureADTenantType {
    AZURE_AD_TENANT_TYPE_COMMON = 0;
    AZURE_AD_TENANT_TYPE_ORGANISATIONS = 1;
    AZURE_AD_TENANT_TYPE_CONSUMERS = 2;
}

message AzureADTenant {
    oneof type {
        AzureADTenantType tenant_type = 1;
        string tenant_id = 2;
    }
}

message AppleConfig {
    string client_id = 1 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"com.client.id\"";
            description: "Client id (App ID or Service ID) provided by Apple";
        }
    ];
    string team_id = 2 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"ALT03JV3OS\"";
            description: "Team ID provided by Apple";
        }
    ];
    string key_id = 3 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "\"OGKDK25KD\"";
            description: "ID of the private key generated by Apple";
        }
    ];
    repeated string scopes = 4 [
        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
            example: "[\"name\", \"email\"]";
            description: "the scopes requested by ZITADEL during the request to Apple";
        }
    ];
}