ContextQMD
Back to Zitadel

External Authentication Flow

apps/docs/content/apis/actions/external-authentication.mdx

5.0.0-base5.3 KB
Original Source

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
  • 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
    • 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
  • 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. <ul><li>0: unspecified</li><li>1: female</li><li>2: male</li><li>3: diverse</li></ul>
    • 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

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