Actions: Access organization metadata in external authentication flow

[vs-gtadeu]

Similar to #7023, I would like to know if making the organization metadata available in actions invoked during the external authentication flow is possible.

The intent here is to implement something as close as possible to Auth0's SAML connection mappings. Support people on our end use this feature to easily configure the conversion of attributes from an external SAML IDP into user attributes since SAML attributes change from customer to customer.

We would achieve this by introducing a generic action that can map SAML attributes from an external IDP to user attributes using a "dynamic map". The action would read the dynamic map from an organization metadata item while our API would create that metadata item via REST/gRPC. The action would be configured for all organizations in Zitadel, but the mappings would be different/customized depending on the organization.

I have considered some alternatives for implementing this, but using the organization metadata with a generic action would be the safest way to proceed, in my opinion. Below are the alternatives I have considered:

1. Allowing support people to "program" a custom action. Not good because:

• Support people are not developers
• Actions could be flaky or introduce vulnerabilities
• It is easy for them to understand and maintain a JSON, but complex to do the same with JavaScript

2. Generating a "dynamic" action: our API could generate a dynamic action from the JSON object. Not good because:

• It could open doors for JavaScript code injection / remote code execution.

[vs-gtadeu]

Any news about this?

[stebenz]

@vs-gtadeu

To summarize, you want the option to map SAML attributes of the external SAML IDP to the user attributes inside ZITADEL.

There are currently two options for this problem:

1. add the SAML attributes to be available in the action with the organization metadata to do dynamic mapping
2. add configuration to the IDP in ZITADEL so that you can map the attributes there, you could also include Ability to use a SAML attribute as the external user ID #7421 (maybe have a look a the LDAP IDP configuration, which could be used as an example)

I would prefer option 2, as it seems cleaner and even if it would take a little more time than option 1 it is still manageable in a short time. Whats your opinion on this 2 solutions?

[vs-gtadeu]

To summarize, you want the option to map SAML attributes of the external SAML IDP to the user attributes inside ZITADEL.

Yes, that is exactly what I'm looking for.

There are currently two options for this problem:

Just checking to see if I understand what you are saying right: you are talking about options for solutions that would require introducing features/changes to Zitadel, correct?

If that is the case, I definitely like option 2 as it would allow us to manage one less Action on our end, and we would rely on Zitadel to perform the mapping. However, timing is important here, so if 1 is quicker to implement, I think that would be preferable.
If 2 is quickly doable, I don't see why not have this implemented the "right way" from the start. If you could throw #7421 there that would be amazing!

[vs-gtadeu]

FWIW, this is the structure of the JSON with the attribute mapping that we were planning to store in the organization metadata:

{
  "preferredUsername": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
  "firstName": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "firstname"
  ],
  "lastName": {
    "attributeName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
  },
  "email": {
    "attributeNames": [
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "email"
    ]
  },
  "location": {
    "attributeName": "location",
    "default": ""
  },
  "hardcoded": {
    "default": "SOME_HARDCODED_VALUE"
  }
}

Basically, there would be 4 different ways to configure the mapping of an attribute:

• Simplified single option: Configuration is just a string containing the SAML attribute name. Only one SAML attribute is acceptable. If not present, the value in Zitadel is set to null or undefined:

  "preferredUsername": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"

• Simplified multi-option: Configuration is an array of strings. Each string is an acceptable SAML attribute name. Only the value of the first attribute found matching one of the names in the array is used (if the others are present, they get ignored):

  "firstName": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "firstname"
  ]

• Complex single option: Similar to the simplified single option, but configured via an object with an attributeName property holding the SAML attribute name:

  "lastName": {
    "attributeName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
  }

• Complex multi-option: Similar to the simplified multi-option, but configured via an object with an attributeNames property holding the SAML attribute names:

   "email": {
    "attributeNames": [
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "email"
    ]
  }

• Complex with default value: Either used with the complex single or multi-option. Allows setting a default value if the attribute is not present:

  "location": {
    "attributeName": "location",
    "default": ""
  }

• Default value only: No attributes are mapped. Only the default value is used:

  "hardcoded": {
    "default": "SOME_HARDCODED_VALUE"
  }

[vs-gtadeu]

I forgot to mention something in the original post. You might have noticed from the example above, but we are also planning to use the same mappings with custom user attributes, not only the ones that compose the user scheme in Zitadel (i.e., username, first name, last name, etc).

Our plan is to store the custom attributes in a metadata field called external as a JSON object. Any attribute in the mapping that doesn't fit Zitadel's user scheme would fall under this metadata field.

Because this use case might be very specific to us, this could be a strong argument for proceeding with option 1 (add the SAML attributes to be available in the action with the organization metadata to do dynamic mapping).

If you think mapping custom attributes makes sense with option 2 (add configuration to the IDP in ZITADEL so that you can map the attributes there), you probably want to make the mappings a bit more generic to indicate where in the metadata the custom attributes would fit (or maybe split the mappings between user mappings a and metadata field mappings).

[vs-gtadeu]

@stebenz @fabius Because time is of the essence, I created a feature request for just providing a way to get the org metadata in an external authentication flow action: #7482

[hifabienne]

@peintnermax @stebenz What is your take on that?

[hifabienne]

this has been shipped with the following PR: #7571