Claim transformation |

If you are member of the role ClaimTransformation then you will see a main tab called “Claim Transformations”. You can use this to set up claim pipeline transformation rules that can be attached to Authentication Connection and Protocol Connection.

Claim Transformations are steps in the Claim Pipeline that transform the claim set attached to a token. The way in which this transformation is done depends on the type of Claim Transformation object. Clicking the “New” button you will see that we offer 9 different types. (Notice that “Create Organization” is not a Claim Transformation object. Administering objects in organizations is explained in Organization Administration article).

Let us look at each of these Claim Transformation objects in turn.

Claim value transformation

This Transformation page makes it possible to add additional values to the claims of a token. It is in terms of the features it supports identical to “User Independent Values for Claims” and “Relying Party Specific Claims” that existed in version 3.1. These two settings no longer exist from version 3.2 since they are replaced by the “Claim Value Transformation” object, but if you are upgrading your solution fear not – your earlier settings will automatically be converted to the mentioned new object so that your pipeline will function identically.

What this Transformation object will do — regardless of how the claim set looks when reaching this step in the pipeline — is add the values of this object to the claim set.

The Transformation consists of the following sections.

Claim Transformation Name: Give the Transformation object a name that will make it easy to recognize when adding to the Pipelines of Authentication and Protocol connections.

Culture: Since expression may be using and comparing numbers, it is important for the system to know what culture is used in order to know whether comma or dot indicates a decimal point. Currently only two cultures are supported, Danish (comma is decimal point) and American (dot is decimal point). These should cover the needs of other cultures in regards to this issue.

Owner Organization: The organization that the Claim Transformation is added to.

Execute before loading claims from local store:By default, a claim transformation rule is executed after claims from local store are loaded for a principal. Check this option to let it execute before the load.

Conditions: It is possible to specify that the Transformation object is only applied to a Pipeline given certain conditions of the token or user is in place. Conditions include:

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Add Claim Value Transformation: The specific values that will be added to claims of a Token when passing by this step. The values will always be an addition to existing values for a token’s claims rather than overwrite them. If e.g. the email claim already has a value for the token before reaching this Transformation object and another value is stated in the object, then the token will after this step have two values for the email claim.

Claim mapping transformation

If you would like to rename or reorganize the claims and their related values before resending them to the Relying Party, you can use this Transformation object. Basically, what the mapping does is to ensure that the claim in the “Source Claim” column will receive the value from the “Destination Claim” column.

When adding a new Claim Mapping transformation object, by default any new claim type will map to itself. But it is also possible to have claim types that never pass on their values, claim types that pass on their values to multiple other claim types, as well as claim types that receive values from multiple other claim types.

The Transformation consists of five sections.

Claim Transformation Name: Give the Transformation object a name that will make it easy to recognize when adding to the Pipelines of Authentication and Protocol connections.

Culture: Since expression may be using and comparing numbers, it is important for the system to know what culture is used in order to know whether comma or dot indicates a decimal point. Currently only two cultures are supported, Danish (comma is decimal point) and American (dot is decimal point). These should cover the needs of other cultures in regards to this issue.

Owner Organization: The organization that the Claim Transformation is added to.

Execute before loading claims from local store: By default, a claim transformation rule is executed after claims from local store are loaded for a principal. Check this option to let it execute before the load.

Conditions: It is possible to specify that the Transformation object is only applied to a Pipeline given certain conditions of the token or user is in place, include:

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Claim Mapping: To add a new claim mapping item to the list, add the source and destination claims in the dropdowns and click the add button. This will add it to the list below that. To remove a mapping you do not want click the Remove button.

Copy claims instead of mapping: As default, the source will be replaced by the destination on the issued claim list. When this checkbox is checked, both the source and the destination will be appeared on the issued claim list.

Let claim types that are not specified in Source pass through this transformation step: As default, only claim mappings in this transformation are passed through. When this checkbox is checked, the claims which are not specified on the transformation are passed through.

Exclude Pass-through claims

If you want to restrict claims from being passed on in the pipeline that have not been added to the Safewhere*Identify list of claim types, then you can use the “Exclude Pass-through Claims” Transformation object. What it will do is simply stop any claim value from passing through, which meets the set filters of the Transformation object.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Exclude Pass-through Claims: If there are claims that you do not want to pass through the pipeline, you may add them to this list. If you only add the claim type without a value, then all claims in a token with that claim type will be filtered out of the token and not passed on. If you also add a value, then only claims with that specific value will be filtered out of the token. Besides, we also support the regexp to filter the values, e.g

Regex:^(?!(miljoe_udinaturen_administrator|miljoe_udinaturen_inddatoer|udinaturen_administrator|udinaturen_inddatoer)$).*

1	Regex:^(?!(miljoe_udinaturen_administrator\|miljoe_udinaturen_inddatoer\|udinaturen_administrator\|udinaturen_inddatoer)$).*

Exclude Safewhere*Identify claims

If you want to restrict claims from being passed on in the pipeline that have been added to the Safewhere*Identify list of claim types, then you can use the “Exclude Safewhere*Identify Claims” Transformation object. What it will do is simply stop any claim value from passing through, which meets the set filters of the Transformation object.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Exclude Safewhere*Identify Claims:If there are claims that you do not want to pass through the pipeline, you may add them to this list. If you only add the claim type without a value, then all claims in a token with that claim type will be filtered out of the token and not passed on. If you also add a value, then only claims with that specific value will be filtered out of the token. Besides, we also support the regexp to filter the values, e.g

Regex:^(?!(miljoe_udinaturen_administrator|miljoe_udinaturen_inddatoer|udinaturen_administrator|udinaturen_inddatoer)$).*

1	Regex:^(?!(miljoe_udinaturen_administrator\|miljoe_udinaturen_inddatoer\|udinaturen_administrator\|udinaturen_inddatoer)$).*

Claim filter

This is basically the opposite of the two “Exclude Pass-through/Safewhere*Identify Claims” transformations, since – rather than specify which claim types that should not be let through – it lists the finite list of claim types that are allowed to pass through. It will although be smarter in some sense, since it will also allow the use of regular expressions to specify the types of values to be allowed through for a claim type.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Claims and Values that will be allowed to pass-through: First step is to select the claim type to be allowed through. This can either be selected from the dropdown of Claim Types that “Exist in Safewhere*Identify” or – by choosing the “Not exist in Safewhere*Identify” radio button – manually inserted. Next step is to specify the allowed values. We here allow the user of regular expressions to specify the range of allowed values. Below are some examples of the allowed formats.

Exact match is just stated as is, e.g.: “UserAdmin”
Matching with anything that starts or ends with a specific word is done using asterisk:
- Ends with something specific, e.g. “*Admin”
- Starts with something specific, e.g. “User*”
- Has a value anywhere in the string, e.g. “*Ad*”
Allow specific positions in string to be replaced by any character, e.g. “User?dmin”
Support of numeric comparisons, e.g.<3; <=3; >3; >=3; =3. Also support for negative values. For the decimal value, make sure you enter correct decimal value according to culture specified in the ClaimTransformation.
Also support of more advanced regular expression syntax. Refer to online resources to learn more on using regular expressions.

SQL transformation

This transformation rule gives a lot of flexibility but should be used with care. The rule is especially smart where you need to save values from the token into external databases, it can also be used for updating the Safewhere*Identify database. A typical example is if you extract information of a new organization from an incoming user’s token and want to have this organization created, then this type of rule is perfect. It could also be used to create new users, if you want them specified in a certain way that does not fit with the existing user creation system in Safewhere*Identify. Another typical situation is when you want to save information from the token to the user, since Safewhere*Identify does not allow to do this.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

SQL Server: Specify the connection string for the database that you wish to interact with and then define the SQL script that must be run against the database.

Connection String: The connection string that will give you access to the used database.
Re-cache Main Data: If the SQL script regards changing organization data in the Safewhere*Identify database, then a re-caching of main data will be necessary. When necessary, set this checkbox to true.
Re-cache User Data: This checkbox is used when updating user data in Safewhere*Identify with the script.
SQL Script: The script that will be used for the database specified in Connection String. You can insert claim type names as in the following example, and the claim type will on runtime be replaced with the value extracted from the claim type of the user’s token. Example:

Update UserTable

Set Email=N'{{http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress}}'

Where username=N'{{http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name}}'

Update UserTable

Set Email=N'{{http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress}}'

Where username=N'{{http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name}}'

External transformation

Although the different transformation rules exist in Safewhere*Identify will cover a lot of different situations, there will still be many scenarios where standard rules does not suffice. It is possible to create your own transformation rule and plug into Safewhere*Identify. Briefly speaking, external claims transformation module enables third parties to write claims transformation rules that are independent from Safewhere*Identify build. Some of the important features are:

It is possible to change an external DLL by simply copying the new DLL to the Safewhere*Identify server, and recycling the app pool.
There is no dependency between the external DLL and a specific build of Safewhere*Identify. The only dependency between the two is the interface that is implemented by the external DLL.
The interface is defined in a strongly named assembly, but its version is fixed as long as there are no breaking changes.
A new build of Safewhere*Identify does not require that the external DLL is recompiled.

Before we set up the External Claim Transformation rule in Safewhere*Identify, we must first prepare the “plugin”.

The processing flow for External Transformation

The processing flow for how a claims principal is exposed to the claims transformation pipeline:

The principal is then passed through the configurable claims transformation rules that are configured to run after the rule that load claims from the local store. External transformations can also be among the rules that are run after claims are loaded from the local store.
The principal then loads claims from the local store.
The principal is then passed through the configurable claims transformation rules that are configured to run before the rule that load claims from the local store. External transformations can be among the rules that run before claims are loaded from the local store.
The principal is passed through Safewhere*Identify’s built-in, hard-coded transformation rules.
User authenticates.
A claims principal is created.
The principal is finally passed through Safewhere*Identify’s other built-in, hard-coded transformation rules.

Steps to implement a new External Transformation

There are three steps.

Reference to the Safewhere.External assembly.
Implement the IExternalClaimsTransformation interface.
Set up the External Transformation to be used in the normal way from Safewhere*Identify’s Administrator pages.

An external custom claims transformation must implement the IExternalClaimsTransformation interface.

public interface IExternalClaimsTransformation

{

IClaimsPrincipal Transform(IClaimsPrincipal principal , IDictionary<string, string> inputs, IExternalClaimTransformationPipelineContext pipelineContext);

}

public interface IExternalClaimsTransformation

{

IClaimsPrincipal Transform(IClaimsPrincipal principal , IDictionary<string, string> inputs, IExternalClaimTransformationPipelineContext pipelineContext);

}

By design, the claims principal object may have more identities.
Each identity provider may add its own identity to the claims principal object at the time the principal object is passed to this transformation rule. The number of identities it contains depends on what previous transformation rules it has passed through.
Typically what happens is:
- After Safewhere*Identify receives a token from an upstream Identity Provider or from the UserNamePassword login, it creates the principal with one identity.
- There is a special built-in transformation which loads claims from the local store into another identity and adds it to the principal (2 identities so far)
- There is a setting called “Execute before loading claims from local store” in the claims transformation configuration page which controls if a transformation should be executed before or after the second identity is added.
- Note 1: It is safe to add a claim to multiple identities because all but one will be filtered out before returning them to the Relying Party.
- Note 2: Other transformations may add more identities to the claims principal.

Exception handling and logging

The interface assembly will provide an interface for logging:

   public interface IIdentifyLogWriter
   {
       void WriteError(object message);
       void WriteError(intmessageId, object message);
       void WriteInformation(object message);
       void WriteInformation(intmessageId, object message);
       void WriteWarning(object message);
       void WriteWarning(intmessageId, object message);
   }

public interface IIdentifyLogWriter

{

void WriteError(object message);

void WriteError(intmessageId, object message);

void WriteInformation(object message);

void WriteInformation(intmessageId, object message);

void WriteWarning(object message);

void WriteWarning(intmessageId, object message);

}

External assemblies can use this interface to logs exception as well as other information to event log at their will.

For unhandled exceptions from an external custom transformation, Safewhere*Identify will log them to the event log. Safewhere*Identify will then either halt the processing pipeline or progress to the next transformation based on the relevant settings.

In order to enable logging to the Safewhere event log, simply add a dependency to the IIdentifyLogWriter interface. For example:

public class AddDummyClaimTransformation : IExternalClaimsTransformation
    {
        private readonly IIdentifyLogWriter identifyLogWriter;

        public AddDummyClaimTransformation(IIdentifyLogWriter identifyLogWriter)
        {
            if (identifyLogWriter == null)
            {
                throw new ArgumentNullException("identifyLogWriter");
            }

            this.identifyLogWriter = identifyLogWriter;
        }

        public IClaimsPrincipal Transform(IClaimsPrincipal principal, IDictionary<string, string> inputs, IExternalClaimTransformationPipelineContext pipelineContext)
        {
            if (principal == null)
            {
                throw new ArgumentNullException("principal");
            }

            try
            {
                var type = GetType();

                foreach (var identity in principal.Identities)
                {
                        identity.Claims.Add(new Claim(type.FullName, type.AssemblyQualifiedName));
                        identifyLogWriter.WriteInformation(string.Format(CultureInfo.InvariantCulture,
                                                                     "A new claim is added: [{0},{1}]", type.FullName, type.AssemblyQualifiedName));
                }
            }
            catch (InvalidOperationException ex)   // this exception type is caught for illustration purpose only
            {
                // Ids from 4830 to 4899 are reserved for external components. Pick one that doesn't conflict with other external events in the same set up
                identifyLogWriter.WriteError(4830, ex);
            }
            return principal;
        }
    }

public class AddDummyClaimTransformation : IExternalClaimsTransformation

{

private readonly IIdentifyLogWriter identifyLogWriter;

public AddDummyClaimTransformation(IIdentifyLogWriter identifyLogWriter)

{

if (identifyLogWriter == null)

{

throw new ArgumentNullException("identifyLogWriter");

}

this.identifyLogWriter = identifyLogWriter;

}

public IClaimsPrincipal Transform(IClaimsPrincipal principal, IDictionary<string, string> inputs, IExternalClaimTransformationPipelineContext pipelineContext)

{

if (principal == null)

{

throw new ArgumentNullException("principal");

}

try

{

var type = GetType();

foreach (var identity in principal.Identities)

{

identity.Claims.Add(new Claim(type.FullName, type.AssemblyQualifiedName));

identifyLogWriter.WriteInformation(string.Format(CultureInfo.InvariantCulture,

"A new claim is added: [{0},{1}]", type.FullName, type.AssemblyQualifiedName));

}

catch (InvalidOperationException ex) // this exception type is caught for illustration purpose only

{

// Ids from 4830 to 4899 are reserved for external components. Pick one that doesn't conflict with other external events in the same set up

identifyLogWriter.WriteError(4830, ex);

}

return principal;

}

Localization

The external plugins will need their own text resources. These text resources will also be used for the custom views.

Safewhere*Identify’s text resource framework is built in a way that allows customize default language. In addition, it is also possible to override default texts with some company-specific resources. But since external DLL are used for a specific installation, where you know what the default language is, you can make the plugin use a simpler text resource model:

Add text resource files to the project.
Text resources files’ properties must be set correctly:
- Build Action: None
- Copy to output: Do not copy
- Custom tool: GlobalResourceProxyGenerator
Upon deploying the DLL, also copy the resource files to appropriate folders.

It is recommended that when logging messages to event log, the external DLL should hard code messages in the language of its choice instead of reading from text resources. Otherwise, messages may be logged in the user’s preferred language.

How to use the Plugin

Drop your DLL into the Tenants\Runtime\bin folder.

Go to Identify*Admin and create a new External Transformation Rule.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

External Claims Transformation: Select the assembly qualified name of the transformation into the Transformation type name dropdown box. The options in this dropdown list will be updated immediately after the DLL files are put into the Bin folder.

If you do not want the pipeline to break down in case the External Plugin failed, then set Continue on Error to True.

Additional settings: Give some predefined settings which will be used on transform on the selected external claim transformation above.

Questions and Answers on using External Transformation

Question: Do I need to wire up my transformation in some Windsor file?
Answer: No, Safewhere*Identify can do the registration job for you at runtime.

Question: What if my transformation has dependency to another service? E.g. what if it has a dependency to IMyCompanyEmailSender service?
Answer: Then unfortunately, you will need to wire your transformation up the IMyCompanyEmailSender in some Windsor file. You still don’t need to wire up the transformation itself, though.

Question: How many identities does a claims principal have?
Answer: A claims principal, by the time it is passed to an external claims transformation, should have two identities; a name claim identity and a local user identity, which contains all the claims that are issued by the local store. The second identity is for claim issuance purpose only. An external transformation can add new claims to either of the two or add to both. Duplicate claims will be filtered out later.

Event IDs

Event IDs used by Safewhere*Identify for this plugin is:

140: External claims transformation error.

LDAP claim transformation

It is important to stress that LDAP attributes store (aka LDAP claims transformation) is not limited to the AD Provider plugin. It is a full, standalone feature on its own. That said, other plugins will be able to use this store for claims transformations against LDAP directories as well.

The Transformation consists of the following sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

LDAP-WS service name: Specifies the LDAP-WS tenant (as specified in LDAP Web Service Settings) that is used for this connection. The LDAP claim transformation cannot be applied without this setting.

LDAP filter: This filter is used to query LDAP for attributes. One should strive for creating a filter that always match to a single user object.samAccountName, userPrincipalName , and email are good candidates to use for this filter when used with AD.

Example: Given that the user logins with NemID and the filter is (LDAP attribute = “globeteamCPRNummer“, Claim type = “dk:gov:saml:attribute:CprNumberIdentifier”). The claims rule will extract CPR Number claim value from claimsprincipal and query LDAP for a user whose globeteamCPRNummer equals to that value. When the filter here may match more than one user, the Primary Account Selector can be used to pick a primary one.

Primary account selector: Specify the LDAP attribute which is used to specify the primary account and the value to be user to filter in “LDAP attribute to specify the primary account” in case the LDAP filter above matches more than one account.

Claim Mapping: It’s used for mapping LDAP attribute values queried from LDAP to claims. For example, it can use to map tokengroups to RoleClaimType.

Additional settings: we extend some settings when doing the mapping the AD user attributes to Identify claim types:

Exclude disabled users
Exclude locked out users
Exclude expired users
Raise error if more than one user is found
Raise error if no users are found
Sort search result by user name

As username, append the following domain to Windows account name when it is asked for

User account update transformation

This transformation rule is used for updating a user’s attributes in the local Identify user store based on claim type values in the user’s token.

This functionality is useful both in scenarios, where incoming tokens define values that should be added to the user account stored in the Identify store as well as scenarios, where rules in Identify’s claims pipeline change the value of the user’s claims and require this change to be saved to his local account in the process. Besides actually specifying the claim type that should be saved locally, the administrator is also able to specify logic for what happens, when a value already exists in the user account that is stored in Safewhere*Identify; i.e. decide whether to overwrite, extend or ignore a user’s existing values.

This is basically done by specifying one or more sets of claims and options. The options specify the rule for how the value from a claim type will be saved to the user’s account.

In the claims pipeline, the claims set’s values by the time the “user account update” transformation is executed will be updated to user account based on the defined rules of this transformation.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Claim Mapping: To add a new “claim to update for user”you must choose both a claim type and an option. The options are <overwrite, extend >. Whenever this transformation step is reached in the pipeline, the value of the specified claim type will be extracted from the token and saved to the local user store for the same claim type and the user in context. The difference between overwrite and extend is the way it affects discrete claims. When “overwrite” is chosen, it means that any prior value for the user will be removed from the local store and replaced by the value in the token. When “extend” is chosen, any value in the token, which does not yet exist in the local store for the user, will be added to any existing value. For free value claims, the chosen option does not matter and any existing value in the store will just be overwritten with value of token’s claim type – if such exists.

NameID format transformation

This Transformation page provides users the ability to change NameID format in the same way as in ADFS 2.0. It helps configure what claim type should be used as NameID, and what the NameID format should be.

The Transformation consists of the following sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

NameID claim mapping: This section helps configure what claim type should be used as NameID, and what the NameID format should be.

There are 2 dropdown lists:

Source: Offers all free claims that exist in Identify.
- There will be a special option called “Name Id” which means the NameID value extracted from a token received from an upstream IdP will be used.

NameID format: includes 5 Items.

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient(*)
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

urn:oasis:names:tc:SAML:2.0:nameid-format:transient(*)

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

(*)When NameID format is Transient, Source will be disabled.

Business logic

1. When a NameID claims transformation is configured, then SAML 2.0 tokens will be issued accordingly: Subject includes the <NameId> whose format is choosen from “NameId format” and value is the value of claim type choosen from “Source”.

2. When no NameID claim transformation is configured, then NameID – where default format is ‘Unspecified’ and default value is logged in user’s identity name. e.g: <NameID Format=”urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified“>admin</NameID> – will be issued.

3. When a NameID claims transformation is configured to use Transient format, the NameID value will be randomly generated. e.g: <NameID Format=”urn:oasis:names:tc:SAML:2.0:nameid-format:transient“>_6341433e-313d-4971-94f9-29a502bd7b69</NameID>

4. When a NameID claims transformation is configured to use Persistent format, it will only issue Name Id with that format, but value is still logged in user’s identity name. e.g: <NameID Format=”urn:oasis:names:tc:SAML:2.0:nameid-format:persistent“>tmhtest</NameID>

In case user want to use Persistent Pseudonym with Persistent Name ID format, he should tick “Use Persistent Pseudonym” in the Protocol Connection, and combined with using a NameID claims transformation which is configured as below:

5. The error will be returned when no claim value or more than one claim values are found.

Scripting transformation

In this kind of transformation, we use C# as a scripting language to do string operations and more.

The Transformation consists of five sections.

The option to skip the Transformation step when the token belongs or does not belong to a user identified as existing in the Safewhere*Identify repository.
The option to specify that the Transformation object is not applied when token is processed via specific Authentication Connection or Protocol Connection.
The option to specify regular expressions that define which tokens are to be exposed to the transformation step. Please see the Using Regular Expressions in Claim Transformation Conditions section to learn more.

Scripting: Input the coding script here. For easy view, click “Open expended editor” to code your script. Besides, we also support some bult-in functions:

GetClaim(string claimType): return the value of the first claim whose claim type equals to the input claim type. Note: claim type is case sensitive
- Usage:

var value = GetClaim(“urn:firstname”);
string value = GetClaim(“urn:firstname”);

1 2	var value = GetClaim(“urn:firstname”); string value = GetClaim(“urn:firstname”);

Exist(string claimType): check if there exists a claim whose claim type equals to the input claim type. Note: claim type is case sensitive.
- Usage:

bool value = Exist(“urn:firstname”);
var value = Exist(“urn:firstname”);

1 2	bool value = Exist(“urn:firstname”); var value = Exist(“urn:firstname”);

Match(string claimType, string valuePattern): check if there exists a claim whose claim type equals to the input claim type and value matches the input value pattern. Note: claim type is case sensitive. Pattern must be a valid regular expression.
- Usage:

bool value = Match(“urn:firstname”, “^Pete”);
var value = Match(“urn:firstname”, “^Pete”);

1 2	bool value = Match(“urn:firstname”, “^Pete”); var value = Match(“urn:firstname”, “^Pete”);

Issue(string claimType, string claimValue): issue a new {claim type, claim value} to the token.
- Usage:

Issue(“urn:firstname”, “Peter”);

1	Issue(“urn:firstname”, “Peter”);

IssueEmptyIfNotExist(string claimType): if the token doesn’t contain any claim whose claim type equals to the input value, issue such a claim with empty value to the token.
- Usage:

IssueEmptyIfNotExist(“urn:firstname”);

1	IssueEmptyIfNotExist(“urn:firstname”);

Add(string claimType, string claimValue): Add a new {claim type, claim value} to the token. The newly added claim will be available for other claim rules to use but will eventually be removed before the token is issued.
- Usage:

Add(“urn:firstname”, “Peter”);

1	Add(“urn:firstname”, “Peter”);

AddEmptyIfNotExist(string claimType): if the token doesn’t contain any claim whose claim type equals to the input value, add such a claim with empty value to the token. The newly added claim will be available for other claim rules to use but will eventually be removed before the token is issued.
- Usage:

AddEmptyIfNotExist(“urn:firstname”);

1	AddEmptyIfNotExist(“urn:firstname”);

Remove(string claimType): remove all claims of input claim type.
- Usage:

Remove(“urn:removeme”);

1	Remove(“urn:removeme”);

Remove(string claimType, string claimValue): remove all claims of input claim type whose values equal to the input claim value. Claim type is case sensitive while claim value is not.
- Usage:

Remove(“urn:removeme”,”RemoveX”);

1	Remove(“urn:removeme”,”RemoveX”);

GuidToBase64WithMd5 (string strword): Refer to 6. Base64Encoder for real life usage of this function.
- Usage:

Remove(“urn:removeme”,”RemoveX”);

1	Remove(“urn:removeme”,”RemoveX”);

GuidToBase64(string guid): Refer to 6. Base64Encoder for real life usage of this function.
- Usage:

if (Exist("dk:gov:saml:attribute:CvrNumberIdentifier") && Exist("dk:gov:saml:attribute:RidNumberIdentifier"))
Issue("dk:gov:saml:attribute/UniqueAccountKey", Concat("xri://", GetClaim("dk:gov:saml:attribute:CvrNumberIdentifier"),"/00000000.0/", 
GuidToBase64(GetClaim("dk:gov:saml:attribute:RidNumberIdentifier"))));

if (Exist("dk:gov:saml:attribute:CvrNumberIdentifier") && Exist("dk:gov:saml:attribute:RidNumberIdentifier"))

Issue("dk:gov:saml:attribute/UniqueAccountKey", Concat("xri://", GetClaim("dk:gov:saml:attribute:CvrNumberIdentifier"),"/00000000.0/",

GuidToBase64(GetClaim("dk:gov:saml:attribute:RidNumberIdentifier"))));

ToBase64(string s): Refer to 6. Base64Encoder for real life usage of this function.
- Usage:

if (Exist("dk:gov:saml:attribute:CvrNumberIdentifier") && Exist("dk:gov:saml:attribute:RidNumberIdentifier"))
Issue("dk:gov:saml:attribute/UniqueAccountKey", Concat("xri://", GetClaim("dk:gov:saml:attribute:CvrNumberIdentifier"),
"/00000000.0/", ToBase64(GetClaim("dk:gov:saml:attribute:RidNumberIdentifier"))));

if (Exist("dk:gov:saml:attribute:CvrNumberIdentifier") && Exist("dk:gov:saml:attribute:RidNumberIdentifier"))

Issue("dk:gov:saml:attribute/UniqueAccountKey", Concat("xri://", GetClaim("dk:gov:saml:attribute:CvrNumberIdentifier"),

"/00000000.0/", ToBase64(GetClaim("dk:gov:saml:attribute:RidNumberIdentifier"))));

Concat(params string[] values): concatenate many strings to a single string.
- Usage:

string newString = Concat(“abc”, “xyz”);
Issue(“urn:fullName”, Concat(GetClaim(“urn:firstName”), “ “, GetClaim(“urn:lastName”)));

1 2	string newString = Concat(“abc”, “xyz”); Issue(“urn:fullName”, Concat(GetClaim(“urn:firstName”), “ “, GetClaim(“urn:lastName”)));

Using regular expressions in Claim transformation objects

To understand the syntax used, please refer to the following page: http://www.lucenetutorial.com/lucene-query-syntax.html.

The main variable used in expressions will obviously be claim types. In order to use a claim type as a variable, it needs to have a variable name. You will see that claims from version 3.3 have had the possibility of variable names added.

Three global keywords are initialized to use as variable names, namely:

identifyname: the Safewhere*Identify Name of a user
organization: the organization that the user belongs to
group: the group that the user belongs to

To give you a brief about how the regular expressions work, below are some basic condition samples using lucene queries:

Assume Identify is set up with the following claim types:

‘Email Address’ claim type whose variable name is email
‘Year of Birth’ claim type whose variable name is birth year

All tokens meet the condition as described in the following examples will be exposed to the transformation step:

Syntax	Explaination	Example
Keyword matching	The tokens whose claim type assigned as variable name contains the specific word.	email:gmail =>Value of ’email’ claim type is “gmail” email:”gmail.com” =>Value of ’email’ claim type is the “gmail.com” phrase.
Wildcard matching	– To perform a single character wildcard search uses the “?” symbol.- To perform a multiple character wildcard search uses the “*” symbol.	email:gma?l =>Value of ’email’ claim type match with the given word with the single word replaced: gmail, gmael, gmaul… email:gmail* =>Value of “email” claim type is starting with “gmail”: gmail.com, gmail.net… email:g*mail =>Value of ’email’ claim type starting with “g” and ending with “mail”: gmail, googlemail,…
Proximity matching	A claim type whose value contain words are a within a specific distance away. To do a proximity search use the tilde, “~”, symbol at the end of a Phrase	email:”gmailcom”~20 =>Value of ’email’ claim type is contain gmail and com words within 20 words of each other.
Range search:	a claim type whose value is between a specific range (the lower and upper bound).Range can be inclusive [] or exclusive () of the upper and lower bounds.	birthyear:[1900 TO 2000] =>Value of birthyear claim type must be from 1900 to 2000 inclusive. birthyear:(1900 TO 2000) =>Value of birthyear claim type must be from 1900 to 2000 exclusive.
Boolean operators& Grouping	Boolean operators allow terms to be combined through logic operators : AND, OR, NOTCombine with grouping, we can form more complex condition expression.	email:gmail OR email:safewhere =>Value of ’email’ claim type is either “gmail” OR “safewhere” email:gmail AND group:admin =>Value of ’email’ claim type is “gmail” AND group is “admin” email:gmail AND NOT birthyear:2000 =>Value of ’email’ claim type is “gmail” AND birthday is not “2000” (email:gmail OR email:safewhere) AND group:admin => Value of ’email’ is either “gmail” OR “safewhere” AND group is “admin”
Escaping Special Characters	The current list special characters are +-&&\|\|!(){}[]^ ” ~*?:\ which is a part of query syntax.In order to escape a special character, use \ before it.	email:a\b =>Value of ’email’ claim type must be ab

Was this helpful ?Good Somewhat Bad

Categories