External Authentication Flow

This flow is executed if the user logs in using an identity provider.

The flow is represented by the following Ids in the API: FLOW_TYPE_EXTERNAL_AUTHENTICATION and 1

Post Authentication

A user has authenticated externally. ZITADEL retrieved and mapped the external information.

The trigger is represented by the following Ids in the API: TRIGGER_TYPE_POST_AUTHENTICATION or 1.

Parameters of Post Authentication Action

• ctx The first parameter contains the following fields
  • accessToken string The access token returned by the identity provider. This can be an opaque token or a JWT.
  • refreshToken string The refresh token returned by the identity provider if there is one. This is most likely to be an opaque token.
  • claimsJSON() idTokenClaims Returns all claims of the id token.
  • getClaim(key) Any Returns the requested id token claim.
  • idToken string The id token provided by the identity provider.
  • v1
    • externalUser externalUser
    • authError string This is a verification errors string representation. If the verification succeeds, this is "none".
    • authRequest auth request
    • httpRequest http request
    • providerInfo Any Returns the response of the provider. In case the provider is a Generic OAuth Provider, the information is accessible through:
      • rawInfo Any
    • org
      • getMetadata() metadataResult
• api The second parameter contains the following fields
  • v1
    • user
      • appendMetadata(string, Any) The first parameter represents the key and the second a value which will be stored. The value is JSON-encoded, so a string is stored with surrounding quotes (e.g. "de").
      • appendMetadataRaw(string, string | Uint8Array | number[]) The first parameter represents the key and the second a value which will be stored as raw bytes without JSON encoding. A string is stored as its plain UTF-8 bytes (e.g. de without quotes), a byte array (Uint8Array or an array of integers between 0 and 255) is stored as-is. Use this if the systems consuming the metadata expect an unencoded value.
  • setFirstName(string) Sets the first name.
  • setLastName(string) Sets the last name.
  • setNickName(string) Sets the nickname.
  • setDisplayName(string) Sets the display name.
  • setPreferredLanguage(string) Sets the preferred language. Please use the format defined in RFC 5646.
  • setPreferredUsername(string) Sets the preferred username.
  • setEmail(string) Sets the email address of the user.
  • setEmailVerified(boolean) Sets the email address verified or unverified.
  • setPhone(string) Sets the phone number of the user.
  • setPhoneVerified(boolean) Sets the phone number verified or unverified.
  • metadata Array of metadata. This function is deprecated, please use api.v1.user.appendMetadata.

Pre Creation

A user selected Register on the overview page after external authentication. ZITADEL did not create the user yet.

The trigger is represented by the following Ids in the API: TRIGGER_TYPE_PRE_CREATION or 2.

Parameters of Pre Creation

• ctx The first parameter contains the following fields

  • v1
    • user (human)
    • authRequest auth request
    • httpRequest http request
    • org
      • getMetadata() metadataResult

• api The second parameter contains the following fields

  • metadata Array of metadata. This function is deprecated, please use api.v1.user.appendMetadata.
  • setFirstName(string) Sets the first name.
  • setLastName(string) Sets the last name.
  • setNickName(string) Sets the nickname.
  • setDisplayName(string) Sets the display name.
  • setPreferredLanguage(string) Sets the preferred language, the string has to be a valid language tag as defined in RFC 5646.
  • setGender(int) Sets the gender.

• 0: unspecified

  • 1: female
  • 2: male
  • 3: diverse
  • setUsername(string) Sets the username.
  • setEmail(string) Sets the email.
  • setEmailVerified(bool) If true the email set is verified without user interaction.
  • setPhone(string) Sets the phone number.
  • setPhoneVerified(bool) If true the phone number set is verified without user interaction.
  • v1
    • user
      • appendMetadata(string, Any) The first parameter represents the key and the second a value which will be stored. The value is JSON-encoded, so a string is stored with surrounding quotes (e.g. "de").
      • appendMetadataRaw(string, string | Uint8Array | number[]) The first parameter represents the key and the second a value which will be stored as raw bytes without JSON encoding. A string is stored as its plain UTF-8 bytes (e.g. de without quotes), a byte array (Uint8Array or an array of integers between 0 and 255) is stored as-is. Use this if the systems consuming the metadata expect an unencoded value.

Post Creation

A user selected Register on the overview page after external authentication and ZITADEL successfully created the user.

The trigger is represented by the following Ids in the API: TRIGGER_TYPE_POST_CREATION or 3.

Parameters of Post Creation

• ctx The first parameter contains the following fields
  • v1
    • getUser() user
    • authRequest auth request
    • httpRequest http request
    • org
      • getMetadata() metadataResult
• api The second parameter contains the following fields
  • userGrants Array of userGrant's
  • v1
    • appendUserGrant( userGrant`)