{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"611666b2-ade4-479c-9183-a98c5b82baa6"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"248f1df2-0e97-4bae-b61c-49263212fb5c"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"A set of built-in transcoders supporting SAML 2.0 ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" objects is provided that support the most frequently needed value types. Most of them support a common set of properties, documented below; a few other properties are defined for specific transcoder types. Since they largely all do the same thing in the same way, they're documented here together.","type":"text"}]},{"type":"paragraph","content":[{"text":"A particular property of the SAML schema is that ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" both carry zero or more ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" children, so it's allowed in general for the transcoders to be asked to generate objects with no values in either direction but may be inappropriate and prevented in specific cases.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements can be mapped to and from ","type":"text"},{"text":"IdPRequestedAttribute","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.IdPRequestedAttribute"}}]},{"text":" objects with the isRequired property correspondingly set.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Properties","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to the ","type":"text"},{"text":"generic properties","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199510553#TranscodingRuleConfiguration-GenericandRequiredProperties"}}]},{"text":", all SAML 2 transcoders support the following:","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1244.0,"localId":"a736cdfc-4684-4c54-a3fd-7d57cee73ede"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[245.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[94.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[392.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[513.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[245.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.name","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[94.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[392.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[513.0]},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"Name","type":"text","marks":[{"type":"code"}]},{"text":" to map to and from","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[245.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.nameFormat","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[94.0]},"content":[{"type":"paragraph","content":[{"text":"URI","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[392.0]},"content":[{"type":"paragraph","content":[{"text":"urn:oasis:names:tc:SAML:2.0:attrname-format:uri","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[513.0]},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"NameFormat","type":"text","marks":[{"type":"code"}]},{"text":" to map to and from","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[245.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.friendlyName","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[94.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[392.0]},"content":[{"type":"paragraph","content":[{"text":"When encoding, the input IdPAttribute's ID","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[513.0]},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"FriendlyName","type":"text","marks":[{"type":"code"}]},{"text":" to encode","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[245.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.encodeType","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[94.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[392.0]},"content":[{"type":"paragraph","content":[{"text":"true ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[513.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to encode values with an ","type":"text"},{"text":"xsi:type","type":"text","marks":[{"type":"code"}]},{"text":" attached","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[245.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.nameFromMetadata ","type":"text"},{"text":"5.1","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[94.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[392.0]},"content":[{"type":"paragraph","content":[{"text":"false","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[513.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to check for a metadata extension tag for naming rules","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Note the default for “saml2.nameFormat” above. If your desired inbound or outbound syntax does not include the ","type":"text"},{"text":"NameFormat","type":"text","marks":[{"type":"code"}]},{"text":" XML Attribute or relies on a different value, then you MUST set it explicitly in the rule.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Metadata-Based Naming ","type":"text"},{"text":"5.1","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"paragraph","content":[{"text":"The transcoders also support an option to rely on SAML metadata extension tags to provide SP-specific naming rules. This is an alternative to the use of the relyingParties approach of naming specific SPs in a rule to limit its use. This feature can be combined with “default” naming via a rule such that the metadata is checked for a per-SP name in preference to the default in a rule, with the default applying in the absence of a tag value applying.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that this approach only works for encoding into SAML, and does not support the decoding side because the “source name” of a SAML Attribute would then not be known to the system independently of a specific SP (the encoding direction works because the source name there is the internal attribute ID, which is required to be specified in the rule).","type":"text"}]},{"type":"paragraph","content":[{"text":"To use this feature, the rule must contain the ","type":"text"},{"text":"saml2.nameFromMetadata","type":"text","marks":[{"type":"strong"}]},{"text":" property set to true. The rule may or may not also contain the default ","type":"text"},{"text":"saml2.name","type":"text","marks":[{"type":"strong"}]},{"text":" (and ","type":"text"},{"text":"saml2.nameFormat","type":"text","marks":[{"type":"strong"}]},{"text":") properties as a fallback.","type":"text"}]},{"type":"paragraph","content":[{"text":"If in use, all SAML 2 transcoders will check for an extension Attribute/tag of the name “http://shibboleth.net/ns/attributes/naming/saml2” whose values contain a space-delimited pair or tuple of the form “","type":"text"},{"text":"id name format","type":"text","marks":[{"type":"em"}]},{"text":"”. The “id” and “name” values MUST be present, and the “format” is optional. A tag may contain multiple values, but only the first value containing the matching attribute ID will be applied.","type":"text"}]},{"type":"paragraph","content":[{"text":"Notably, in the absence of a third value (the format), the encoded ","type":"text"},{"text":"NameFormat","type":"text","marks":[{"type":"code"}]},{"text":" will be absent/null, rather than defaulting to the URI format constant. This is because in most cases when using this feature, the SP in question is almost certainly broken enough to improperly ignore that value anyway. Leaving it out is usually advisable, unless testing indicates its needed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Whether this approach is better for you really depends on how you manage and curate metadata and your ability to extend it, which is increasingly the key to most effectively operating the Shibboleth software.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example","type":"text"}]},{"type":"paragraph","content":[{"text":"Consider an SP (let’s call it Sluck), that requires mail, givenName, and sn to be supplied using invented Attribute names, in contravention to the SAML standard. To enable metadata-based naming override, the ","type":"text"},{"text":"saml2.nameFromMetadata","type":"text","marks":[{"type":"strong"}]},{"text":" property flag has to be added to each of the rules (all three in this case are in ","type":"text"},{"text":"conf/attributes/inetOrgPerson.xml","type":"text","marks":[{"type":"em"}]},{"text":"). The metadata for Sluck would then contain the following extension block:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n...\n \n \n \n \n \n \n mail email\n givenName first_name\n sn first_name\n \n \n \n \n \n...\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Transcoder Types","type":"text"}]},{"type":"paragraph","content":[{"text":"There are 5 built-in subtypes of SAML 2 transcoders, as follows. Each one is predefined as a Spring bean for use in rules using the \"short\" name of the class, as enumerated in the ","type":"text"},{"text":"TranscodingRuleConfiguration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP5/pages/3199510553"}}]},{"text":" reference section.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SAML2StringAttributeTranscoder","type":"text"}]},{"type":"paragraph","content":[{"text":"The simplest and most commonly used transcoder, it supports encoding and decoding internal values from and to the ","type":"text"},{"text":"StringAttributeValue","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.StringAttributeValue"}}]},{"text":" class. It supports no additional properties.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SAML2ScopedStringAttributeTranscoder","type":"text"}]},{"type":"paragraph","content":[{"text":"It supports encoding and decoding internal values from and to the ","type":"text"},{"text":"ScopedStringAttributeValue","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.ScopedStringAttributeValue"}}]},{"text":" class. It supports the following additional properties (all optional):","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1244.0,"localId":"04b0f5b8-69e7-49b9-9a8c-767a59389a68"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[239.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[183.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[92.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[730.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[239.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.scopeType","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[183.0]},"content":[{"type":"paragraph","content":[{"text":"\"inline\" or \"attribute\"","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[92.0]},"content":[{"type":"paragraph","content":[{"text":"\"inline\"","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[730.0]},"content":[{"type":"paragraph","content":[{"text":"The \"style\"/syntax with which to encode and decode the scope portion","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[239.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.scopeAttributeName","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[183.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[92.0]},"content":[{"type":"paragraph","content":[{"text":"Scope","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[730.0]},"content":[{"type":"paragraph","content":[{"text":"The name of the XML attribute to encode and decode the scope portion when saml2.scopeType is \"attribute\"","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[239.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.scopeDelimiter","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[183.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[92.0]},"content":[{"type":"paragraph","content":[{"text":"@","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[730.0]},"content":[{"type":"paragraph","content":[{"text":"The character(s) to use to separate the value and scope when saml2.scopeType is \"inline\"","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SAML2DateTimeAttributeTranscoder","type":"text"}]},{"type":"paragraph","content":[{"text":"It supports encoding and decoding internal values from and to the ","type":"text"},{"text":"DateTimeAttributeValue","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.DateTimeAttributeValue"}}]},{"text":" class. It supports the following additional properties (all optional):","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1244.0,"localId":"e345018f-f401-420d-8aee-1924c00f465c"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[257.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[84.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[813.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[257.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.epochUnits","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[84.0]},"content":[{"type":"paragraph","content":[{"text":"“s“ or “ms”","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.0]},"content":[{"type":"paragraph","content":[{"text":"“s”","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[813.0]},"content":[{"type":"paragraph","content":[{"text":"When decoding, controls the handling of integer values (or strings in that form) when converting to an ","type":"text"},{"text":"Instant","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.net/cgi-bin/java-jdk.cgi/java/time/Instant"}}]},{"text":". The default (“s”) is to handle the value as seconds, while “ms” means to handle as milliseconds. Java tends to deal in the latter but the traditional handling (e.g., C/C++) tend to be in seconds.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SAML2ByteAttributeTranscoder","type":"text"}]},{"type":"paragraph","content":[{"text":"It supports encoding and decoding internal values from and to the ","type":"text"},{"text":"ByteAttributeValue","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.ByteAttributeValue"}}]},{"text":" class, with a base64 transform applied. It supports no additional properties.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SAML2XMLObjectAttributeTranscoder","type":"text"}]},{"type":"paragraph","content":[{"text":"It supports encoding and decoding internal values from and to the ","type":"text"},{"text":"XMLObjectAttributeValue","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-attribute.cgi/net.shibboleth.idp.attribute.XMLObjectAttributeValue"}}]},{"text":" class. It supports the following additional properties (all optional):","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1234.0,"localId":"93753b5a-ccac-490e-8867-104ccfe1f2e8"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[256.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[83.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[89.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[806.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[256.0]},"content":[{"type":"paragraph","content":[{"text":"saml2.includeAttributeValue","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[83.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[89.0]},"content":[{"type":"paragraph","content":[{"text":"false","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[806.0]},"content":[{"type":"paragraph","content":[{"text":"When decoding, controls whether the decoded XMLObject is actually the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element itself, or its child element","type":"text"}]}]}]}]},{"type":"paragraph"}],"version":1}

Browser not supported